- document Source and Details workflows, diagnostics, preview controls, and draft recovery\n- expand llms.txt and llms-full.txt with current product guidance and regression checks\n- refresh portable skill links, appearance review guidance, and published packages
- commit
- 3561e26b38a8ffea85d4409dd4ffea13ca0df78b
- parent
- b6d14f1e53c054fdc1f3d6ae5cd29cd92dc197cf
- author
- Dami <dami.etoile@gmail.com>
@@ -9,6 +9,9 @@ sidebar_position: 1
99 1010 Save a diagram before you share it. A saved diagram has a stable read link.1111 12+The Share dialog contains link controls and privacy controls. Lock, password13+change, and password removal actions stay beside the content they affect.14+1215 ## Read links1316 1417 A read link lets a person open the saved diagram. The link has this form:@@ -42,6 +45,9 @@ it for that alias and removes it from the address bar. A copied page URL is
4245 therefore normally a read link. Copy the edit link from the Share dialog when4346 you need to share write access.4447 48+Copy actions report success or failure in a short-lived toast above the dialog49+backdrop.50+4551 For a locked diagram, an edit link does not replace the password. The person4652 needs both the edit capability and the password.4753 @@ -15,6 +15,12 @@ you save.
1515 The working state is what you currently see and edit. It includes the diagram1616 source, type, renderer options, presentation settings, title, and description.1717 18+Source and Details use separate editor tabs. Details is a JSON document that19+contains the title, description, and presentation settings.20+21+Invalid Details JSON remains in the local draft. The editor keeps the last22+valid preview and blocks save, share, privacy, and type changes until it is valid.23+1824 When you edit a saved diagram, the working state changes first. The saved1925 diagram does not change until you choose **Save**.2026 @@ -22,6 +28,9 @@ For an open diagram, diagram.zip stores the working state as a local browser
2228 draft. This draft supports recovery on the same browser. It is not a saved2329 diagram and other people cannot read it.2430 31+An edited anonymous example shows a reset icon. Reset removes its local draft32+and restores the bundled example after confirmation.33+2534 When a saved link opens with a different local draft, the editor marks that2635 draft as a device-only overlay. Choose **Restore saved** to discard the overlay2736 and return to the alias revision, or **Make a copy** to preserve it under a new@@ -30,6 +39,9 @@ alias. Neither action silently changes the original share link.
3039 For a locked diagram, the editor does not store the working state as plaintext3140 in browser storage. Save a locked diagram explicitly to persist it.3241 42+Zoom and pan are preview session state, not saved diagram state. Appearance43+changes and Edit or Preview tab switches preserve the current view position.44+3345 ## Saved state3446 3547 The saved state is the last version that you saved successfully. It has an@@ -12,10 +12,11 @@ Start with a diagram type. Each type page shows the source format, a small examp
1212 1313 1. Choose a type from the [diagram type list](/).1414 2. Open its **Syntax** page.15-3. Copy the example into diagram.zip.15+3. Copy the example into the **Source** tab.1616 4. Replace the example labels and connections.17-5. Check the preview.18-6. Save the diagram when you want a stable link.17+5. Edit metadata or presentation in the **Details** tab when needed.18+6. Check the preview.19+7. Save the diagram when you want a stable link.1920 2021 ## Choose a type2122 @@ -25,12 +26,28 @@ When you choose a type in the editor, diagram.zip records it in the page URL as
2526 `?type={type}`. Reloading or copying that working URL keeps the same active type.2627 Saved read and edit links remain alias-based and do not depend on this query.2728 28-## Source and preview29+## Source, Details, and preview2930 30-The source editor is the working state. The preview updates as you edit. A syntax error can stop the preview from rendering. Read the type page when the error points to a language rule.31+The left pane has **Source** and **Details** tabs. Source contains the selected diagram language. Details contains validated JSON for metadata and presentation.32+33+The diagnostics dock below the editors reports Details validation. Invalid Details JSON keeps the last valid preview and blocks actions that require valid state.34+35+The preview updates as you edit. A source syntax error can stop rendering and appears in a short-lived toast at the lower right.36+37+The preview toolbar controls zoom, fit, raw output, theme, and transparency. Appearance changes preserve the current zoom and pan position.38+39+The preview theme affects only the output pane. The application continues to follow the browser or operating-system color preference.3140 3241 Structured types, such as BPMN, Diagrams.net, Excalidraw, UMLet, Vega, and WaveDrom, use XML or JSON. Keep valid document structure when you edit these types.3342 43+Read [General presentation settings](/style/presentation/) for the Details document schema and appearance values.44+45+## Local drafts46+47+Open diagrams keep unsaved changes in local browser storage. An edited example shows a reset icon that restores its bundled source and details.48+49+Saved links use a separate device-only overlay for local changes. Read [Working state and saved state](/collaboration/working-and-saved-state/) before restoring or copying that overlay.50+3451 ## Save or share3552 3653 Use **Save** to create a saved revision. Use a read link when people only need to view the diagram.@@ -12,7 +12,7 @@ import TypeGrid from '@site/src/components/TypeGrid';
1212 1313 # Create and control a diagram.1414 15-Diagram.zip is a browser-based diagram editor. Write or paste source, see the result, then save or share it.15+Diagram.zip is a browser-based diagram editor. Write or paste source, edit structured details, inspect the result, then save or share it.1616 1717 <div className="homeActions">1818 <Link className="button button--primary button--lg" to="/create/">Create a diagram</Link>@@ -21,8 +21,8 @@ Diagram.zip is a browser-based diagram editor. Write or paste source, see the re
2121 2222 ## Find a topic2323 24-- **Create**: choose a diagram type and learn its short syntax guide.25-- **Style**: set common presentation options, then use type-specific settings.24+- **Create**: choose a diagram type, edit Source and Details, and learn its short syntax guide.25+- **Style**: set common presentation options in Details, then use type-specific settings.2626 - **Share**: understand read links, edit links, encryption, and saved state.2727 2828 The pages use short examples and direct links. Agents can use the same stable URLs and code blocks.@@ -1,25 +1,42 @@
11 ---22 id: presentation33 title: General presentation settings4-description: Choose a shared appearance or keep the renderer canvas, padding, and frame.4+description: Edit diagram metadata and choose a shared or renderer-defined presentation.55 sidebar_position: 166 ---77 88 # General presentation settings99 10-Open **Details**, then use **Appearance** to choose how diagram.zip presents the SVG.10+Open the **Details** tab in the left pane. It contains a validated JSON document for metadata and presentation.11+12+```json13+{14+ "title": "Service flow",15+ "description": "A request moving through the public API.",16+ "presentation": {17+ "appearance": "auto-transparent",18+ "background": "",19+ "padding": 0,20+ "frame": false21+ }22+}23+```24+25+`title` accepts at most 200 characters. `description` accepts at most 2,000 characters. Unknown properties are rejected.26+27+The diagnostics dock reports invalid JSON or schema values. Diagram.zip keeps the last valid preview until the document becomes valid again.1128 1229 ## Appearance1330 14-**Renderer default** keeps the safe renderer output. It also enables the canvas, padding, and frame controls.31+`raw` keeps the safe renderer output. It enables the custom background, padding, and frame values in the presentation document.1532 1633 The shared appearances apply one Diagram.zip palette to supported renderer output:1734 18-- **Match device** includes light and dark palettes in one SVG. The SVG selects a palette with `prefers-color-scheme`.19-- **Light** always uses the light palette.20-- **Dark** always uses the dark palette.21-- **Transparent** does not add an outer canvas.22-- **Framed** adds a matching canvas, standard padding, and a border.35+- `auto-transparent` and `auto-framed` include both palettes. The SVG selects one with `prefers-color-scheme`.36+- `light-transparent` and `light-framed` always use the light palette.37+- `dark-transparent` and `dark-framed` always use the dark palette.38+- Transparent appearances omit the outer canvas.39+- Framed appearances add a matching canvas, standard padding, and a border.2340 2441 The editor disables appearances that the current renderer profile cannot support. Diagrams.net supports raw and framed appearances while its authored paint remains unchanged.2542 @@ -27,19 +44,29 @@ Excalidraw and TikZ support every appearance. Their neutral canvas, ink, and lin
2744 2845 Read [SVG normalization and version contracts](/style/svg-normalization) for capability levels, renderer version selection, and artifact metadata.2946 47+## Preview controls48+49+The preview toolbar offers **Raw**, a theme icon, and a transparency icon. These controls rewrite the appearance value in Details.50+51+The theme icon switches only the preview between explicit light and dark output. It does not change the application or system preference.52+53+The transparency icon switches between transparent and framed output. Raw, theme, and transparency changes preserve the current preview zoom and pan position.54+3055 ## Background3156 32-Choose **Renderer default** before you set the background. Use a light background for most documents. Check the contrast of labels and lines after you change it.57+Set `appearance` to `raw` before you set `background`. Use an empty string for the renderer default or a six-digit hexadecimal color.58+59+Check label and line contrast after changing the background.3360 3461 ## Padding3562 3663 Padding adds space around the rendered diagram. Use a small value for an inline image. Use a larger value when a frame or a presentation layout needs more space.3764 38-The supported range is **0 to 256 pixels**.65+`padding` must be an integer from **0 to 256 pixels**.3966 4067 ## Frame4168 42-Turn the frame on when the diagram needs a clear boundary. Turn it off when another page or card already provides the boundary.69+Set `frame` to `true` when raw output needs a clear boundary. Set it to `false` when another surface provides the boundary.4370 4471 ## Type-specific styling4572 @@ -50,8 +77,8 @@ For example, [Mermaid styling](/style/types/mermaid/) uses Mermaid configuration
5077 ## A safe order5178 5279 1. Choose a shared appearance when the renderer supports it.53-2. Use **Renderer default** when you need custom canvas controls.80+2. Use `raw` when you need custom canvas values.5481 3. Apply type-specific styles.55-4. Check the preview at its target size.82+4. Check light, dark, and transparent output at the target size.5683 5784 A **Renderer options** section appears only when the renderer adds options for that type.@@ -10,7 +10,7 @@ sidebar_label: ActDiag
1010 1111 ActDiag supports lane, action, edge, and diagram attributes.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: BlockDiag
1010 1111 BlockDiag supports diagram attributes and per-node or per-edge attributes.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: BPMN
1010 1111 BPMN appearance usually comes from BPMN diagram interchange data and renderer defaults.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Bytefield
1010 1111 Bytefield uses drawing-form properties for spans, labels, and layout.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: C4 PlantUML
1010 1111 C4 PlantUML supports layout macros, tags, legends, and PlantUML style controls.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: D2
1010 1111 D2 supports themes, shape properties, style blocks, classes, and sketch mode.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: DBML
1010 1111 DBML describes schema structure. It does not define visual presentation.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Diagrams.net
1010 1111 Diagrams.net stores geometry and style values on cells in the XML source.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Ditaa
1010 1111 Ditaa supports shape tags, color tags, dashed lines, and renderer options.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: ERD
1010 1111 ERD focuses on the data model. The renderer controls most visual values.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Excalidraw
1010 1111 Excalidraw stores the style of each element in the JSON source.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: GoAT
1010 1111 GoAT takes most geometry from the text. Renderer options control SVG colors and character handling.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Graphviz
1010 1111 DOT supports graph, node, and edge attributes.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Mermaid
1010 1111 Mermaid supports themes, frontmatter configuration, class definitions, and diagram-specific configuration.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Nomnoml
1010 1111 Nomnoml uses hash directives and custom classifier styles.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: NwDiag
1010 1111 NwDiag supports network and host attributes.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: PacketDiag
1010 1111 PacketDiag supports global layout values and field attributes.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Pikchr
1010 1111 Pikchr supports dimensions, colors, fills, line widths, and placement controls in the source.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: PlantUML
1010 1111 PlantUML supports themes, skin parameters, colors, sprites, and element-specific style rules.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: RackDiag
1010 1111 RackDiag supports rack and device attributes.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: SeqDiag
1010 1111 SeqDiag supports participant, message, and diagram attributes.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Structurizr
1010 1111 Structurizr supports workspace styles, themes, tags, and automatic layout.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Svgbob
1010 1111 Svgbob takes geometry from the text and supports renderer-level SVG settings.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Symbolator
1010 1111 Symbolator gets structure from hardware source. Renderer options control the title, scale, and output details.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: TikZ
1010 1111 TikZ supports colors, line forms, fills, node styles, scopes, and reusable style definitions.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: UMLet
1010 1111 UMLet stores position and style commands in the UXF XML source.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Vega
1010 1111 Vega controls presentation through scales, mark encodings, axes, legends, and configuration.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: Vega-Lite
1010 1111 Vega-Lite controls presentation through marks, encodings, scales, axes, legends, and configuration.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: WaveDrom
1010 1111 WaveDrom supports source configuration, signal attributes, and a limited set of bundled skins.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -10,7 +10,7 @@ sidebar_label: WireViz
1010 1111 WireViz uses YAML properties for connector, cable, wire, and output styles.1212 13-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.13+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.1414 1515 ## Source controls1616 @@ -117,6 +117,13 @@ try { catalog = JSON.parse(catalogRaw) } catch { errors.push('static/diagram-typ
117117 assert(catalog?.diagramTypes?.length === expected.length, 'Machine catalog does not contain all diagram types.')118118 assert(JSON.stringify((catalog?.diagramTypes ?? []).map(({ id }) => id).sort()) === JSON.stringify(expected), 'Machine catalog IDs do not match the diagram type catalog.')119119 120+const llms = await source(join(site, 'static', 'llms.txt'))121+const llmsFull = await source(join(site, 'static', 'llms-full.txt'))122+assert(llms.includes('https://docs.diagram.zip/create/'), 'llms.txt does not link the editor workspace guide.')123+assert(llms.includes('https://docs.diagram.zip/style/presentation/'), 'llms.txt does not link the Details presentation guide.')124+assert(llmsFull.includes('# General presentation settings'), 'llms-full.txt does not include the presentation guide.')125+assert(llmsFull.includes('# Working state and saved state'), 'llms-full.txt does not include the working-state guide.')126+120127 const expectedSkillIds = [...diagramSkillIds].sort()121128 const skillEntries = await readdir(skills, { withFileTypes: true })122129 const actualSkillIds = skillEntries.filter((entry) => entry.isDirectory()).map(({ name }) => name).sort()@@ -109,7 +109,7 @@ function stylePage(type) {
109109 ? `\n## Renderer options\n\n${options(type)}\n`110110 : ''111111 return frontmatter(type, 'style', `Style a ${type.label} diagram in diagram.zip.`) +112-`# Style ${type.label}\n\n${type.styleSummary}\n\nStart with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.\n\n## Source controls\n\n${lines(type.sourceStyle).map((item) => `- ${item}`).join('\n')}\n${rendererOptions}` +112+`# Style ${type.label}\n\n${type.styleSummary}\n\nStart with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.\n\n## Source controls\n\n${lines(type.sourceStyle).map((item) => `- ${item}`).join('\n')}\n${rendererOptions}` +113113 (limitations.length ? `## Limitations\n\n${limitations.map((item) => `- ${item}`).join('\n')}\n\n` : '') +114114 `## Related pages\n\n- [Create ${article} ${type.label} diagram](${syntaxPath(type.id)})\n- [General presentation settings](/style/presentation)\n- [SVG normalization and version contracts](/style/svg-normalization)\n- [Open ${type.label} in the editor](${editorLink(type.id)})\n`115115 }@@ -126,7 +126,19 @@ const catalog = diagramTypes.map((type) => ({
126126 editor: editorLink(type.id),127127 example: `/examples/${type.id}.json`,128128 }))129-const fullText = () => diagramTypes.map((type) => `${syntaxPage(type, false)}\n${stylePage(type)}`).join('\n---\n\n')129+const coreDocPaths = [130+ join(docs, 'create', 'index.md'),131+ join(docs, 'style', 'presentation.md'),132+ join(docs, 'style', 'svg-normalization.md'),133+ join(docs, 'collaboration', 'sharing.md'),134+ join(docs, 'collaboration', 'encryption.md'),135+ join(docs, 'collaboration', 'working-and-saved-state.md'),136+]137+const fullText = async () => {138+ const coreText = await Promise.all(coreDocPaths.map((path) => readFile(path, 'utf8')))139+ const rendererText = diagramTypes.map((type) => `${syntaxPage(type, false)}\n${stylePage(type)}`)140+ return [...coreText, ...rendererText].join('\n---\n\n')141+}130142 131143 await rm(join(docs, 'create', 'types'), { recursive: true, force: true })132144 await rm(join(docs, 'style', 'types'), { recursive: true, force: true })@@ -146,7 +158,7 @@ await Promise.all(diagramTypes.flatMap((type) => [
146158 await Promise.all(diagramSkills.map(({ id }) => cp(join(skillsDir, id), join(publicSkillsDir, id), { recursive: true })))147159 await writeFile(join(staticDir, 'diagram-types.json'), `${JSON.stringify({ version: 1, diagramTypes: catalog }, null, 2)}\n`)148160 await writeFile(join(staticDir, 'diagram-skills.json'), `${JSON.stringify({ version: 1, groups: skillGroups, skills: skillCatalog, standards: standardsSupport }, null, 2)}\n`)149-await writeFile(join(staticDir, 'llms.txt'), `# diagram.zip documentation\n\n> Choose the semantic story first, then choose a renderer and source format.\n\n- [Diagram routing skill](https://docs.diagram.zip/skills/diagramming/SKILL.md): Select a diagram family from the reader's question.\n- [Machine-readable semantic catalog](https://docs.diagram.zip/diagram-skills.json): Inspect every skill, use case, exclusion, role, and invocation constraint.\n\n${skillIndex()}\n\n## Renderer and source formats\n\n${diagramTypes.map((type) => `- [${type.label} syntax](https://docs.diagram.zip${syntaxPath(type.id)}/): Create ${articleFor(type.label)} ${type.label} diagram. [Style](https://docs.diagram.zip${stylePath(type.id)}/).`).join('\n')}\n\n## General pages\n\n- [General presentation](https://docs.diagram.zip/style/presentation/)\n- [SVG normalization and version contracts](https://docs.diagram.zip/style/svg-normalization/)\n- [Share a diagram](https://docs.diagram.zip/collaboration/sharing/)\n- [Password encryption](https://docs.diagram.zip/collaboration/encryption/)\n- [Working state and saved state](https://docs.diagram.zip/collaboration/working-and-saved-state/)\n\n## Structured catalogs\n\n- [diagram-skills.json](https://docs.diagram.zip/diagram-skills.json)\n- [diagram-types.json](https://docs.diagram.zip/diagram-types.json)\n- [Full renderer text reference](https://docs.diagram.zip/llms-full.txt)\n- [Source repository](https://github.com/FelineStateMachine/diagramzip)\n`)150-await writeFile(join(staticDir, 'llms-full.txt'), `# diagram.zip documentation\n\n${fullText()}`)161+await writeFile(join(staticDir, 'llms.txt'), `# diagram.zip documentation\n\n> Choose the semantic story first. Use Source for notation and Details for metadata and presentation.\n\n- [Diagram routing skill](https://docs.diagram.zip/skills/diagramming/SKILL.md): Select a diagram family from the reader's question.\n- [Machine-readable semantic catalog](https://docs.diagram.zip/diagram-skills.json): Inspect every skill, use case, exclusion, role, and invocation constraint.\n\n${skillIndex()}\n\n## Renderer and source formats\n\n${diagramTypes.map((type) => `- [${type.label} syntax](https://docs.diagram.zip${syntaxPath(type.id)}/): Create ${articleFor(type.label)} ${type.label} diagram. [Style](https://docs.diagram.zip${stylePath(type.id)}/).`).join('\n')}\n\n## General pages\n\n- [Editor workspace](https://docs.diagram.zip/create/)\n- [Details JSON and presentation](https://docs.diagram.zip/style/presentation/)\n- [SVG normalization and version contracts](https://docs.diagram.zip/style/svg-normalization/)\n- [Share a diagram](https://docs.diagram.zip/collaboration/sharing/)\n- [Password encryption](https://docs.diagram.zip/collaboration/encryption/)\n- [Working state and saved state](https://docs.diagram.zip/collaboration/working-and-saved-state/)\n\n## Structured catalogs\n\n- [diagram-skills.json](https://docs.diagram.zip/diagram-skills.json)\n- [diagram-types.json](https://docs.diagram.zip/diagram-types.json)\n- [Full documentation text](https://docs.diagram.zip/llms-full.txt)\n- [Source repository](https://github.com/FelineStateMachine/diagramzip)\n`)162+await writeFile(join(staticDir, 'llms-full.txt'), `# diagram.zip documentation\n\n${await fullText()}`)151163 152164 console.log(`Generated ${diagramTypes.length} renderer guides, ${diagramSkills.length} semantic skill packages, and machine-readable indexes.`)@@ -1,5 +1,571 @@
11 # diagram.zip documentation22 3+---4+title: Create a diagram5+description: Choose a diagram type and create a diagram in diagram.zip.6+sidebar_position: 17+---8+9+# Create a diagram10+11+Start with a diagram type. Each type page shows the source format, a small example, and the syntax that you need first.12+13+## A simple workflow14+15+1. Choose a type from the [diagram type list](/).16+2. Open its **Syntax** page.17+3. Copy the example into the **Source** tab.18+4. Replace the example labels and connections.19+5. Edit metadata or presentation in the **Details** tab when needed.20+6. Check the preview.21+7. Save the diagram when you want a stable link.22+23+## Choose a type24+25+Use the filter on the [diagram type list](/) to search by name, format, or purpose. The list has one syntax page and one style page for every supported type.26+27+When you choose a type in the editor, diagram.zip records it in the page URL as28+`?type={type}`. Reloading or copying that working URL keeps the same active type.29+Saved read and edit links remain alias-based and do not depend on this query.30+31+## Source, Details, and preview32+33+The left pane has **Source** and **Details** tabs. Source contains the selected diagram language. Details contains validated JSON for metadata and presentation.34+35+The diagnostics dock below the editors reports Details validation. Invalid Details JSON keeps the last valid preview and blocks actions that require valid state.36+37+The preview updates as you edit. A source syntax error can stop rendering and appears in a short-lived toast at the lower right.38+39+The preview toolbar controls zoom, fit, raw output, theme, and transparency. Appearance changes preserve the current zoom and pan position.40+41+The preview theme affects only the output pane. The application continues to follow the browser or operating-system color preference.42+43+Structured types, such as BPMN, Diagrams.net, Excalidraw, UMLet, Vega, and WaveDrom, use XML or JSON. Keep valid document structure when you edit these types.44+45+Read [General presentation settings](/style/presentation/) for the Details document schema and appearance values.46+47+## Local drafts48+49+Open diagrams keep unsaved changes in local browser storage. An edited example shows a reset icon that restores its bundled source and details.50+51+Saved links use a separate device-only overlay for local changes. Read [Working state and saved state](/collaboration/working-and-saved-state/) before restoring or copying that overlay.52+53+## Save or share54+55+Use **Save** to create a saved revision. Use a read link when people only need to view the diagram.56+57+Use an edit link when people must save changes. Read [Share a diagram](/collaboration/sharing/) before you send an edit link.58+59+---60+61+---62+id: presentation63+title: General presentation settings64+description: Edit diagram metadata and choose a shared or renderer-defined presentation.65+sidebar_position: 166+---67+68+# General presentation settings69+70+Open the **Details** tab in the left pane. It contains a validated JSON document for metadata and presentation.71+72+```json73+{74+ "title": "Service flow",75+ "description": "A request moving through the public API.",76+ "presentation": {77+ "appearance": "auto-transparent",78+ "background": "",79+ "padding": 0,80+ "frame": false81+ }82+}83+```84+85+`title` accepts at most 200 characters. `description` accepts at most 2,000 characters. Unknown properties are rejected.86+87+The diagnostics dock reports invalid JSON or schema values. Diagram.zip keeps the last valid preview until the document becomes valid again.88+89+## Appearance90+91+`raw` keeps the safe renderer output. It enables the custom background, padding, and frame values in the presentation document.92+93+The shared appearances apply one Diagram.zip palette to supported renderer output:94+95+- `auto-transparent` and `auto-framed` include both palettes. The SVG selects one with `prefers-color-scheme`.96+- `light-transparent` and `light-framed` always use the light palette.97+- `dark-transparent` and `dark-framed` always use the dark palette.98+- Transparent appearances omit the outer canvas.99+- Framed appearances add a matching canvas, standard padding, and a border.100+101+The editor disables appearances that the current renderer profile cannot support. Diagrams.net supports raw and framed appearances while its authored paint remains unchanged.102+103+Excalidraw and TikZ support every appearance. Their neutral canvas, ink, and line paint adapt while authored non-neutral paint remains renderer-defined.104+105+Read [SVG normalization and version contracts](/style/svg-normalization) for capability levels, renderer version selection, and artifact metadata.106+107+## Preview controls108+109+The preview toolbar offers **Raw**, a theme icon, and a transparency icon. These controls rewrite the appearance value in Details.110+111+The theme icon switches only the preview between explicit light and dark output. It does not change the application or system preference.112+113+The transparency icon switches between transparent and framed output. Raw, theme, and transparency changes preserve the current preview zoom and pan position.114+115+## Background116+117+Set `appearance` to `raw` before you set `background`. Use an empty string for the renderer default or a six-digit hexadecimal color.118+119+Check label and line contrast after changing the background.120+121+## Padding122+123+Padding adds space around the rendered diagram. Use a small value for an inline image. Use a larger value when a frame or a presentation layout needs more space.124+125+`padding` must be an integer from **0 to 256 pixels**.126+127+## Frame128+129+Set `frame` to `true` when raw output needs a clear boundary. Set it to `false` when another surface provides the boundary.130+131+## Type-specific styling132+133+General presentation settings do not replace the style rules in the source language. Open the **Style** page for a type to learn its source controls.134+135+For example, [Mermaid styling](/style/types/mermaid/) uses Mermaid configuration. [Graphviz styling](/style/types/graphviz/) uses DOT attributes.136+137+## A safe order138+139+1. Choose a shared appearance when the renderer supports it.140+2. Use `raw` when you need custom canvas values.141+3. Apply type-specific styles.142+4. Check light, dark, and transparent output at the target size.143+144+A **Renderer options** section appears only when the renderer adds options for that type.145+146+---147+148+---149+id: svg-normalization150+title: SVG normalization and version contracts151+description: Understand normalized SVG, renderer version selection, capability metadata, and consumer guarantees.152+sidebar_position: 2153+---154+155+# SVG normalization and version contracts156+157+Diagram.zip accepts SVG from renderers with different structures, palettes, and release cycles. A shared pipeline turns that output into safe, predictable artifacts.158+159+```text160+renderer SVG161+ -> sanitization162+ -> canonical normalization163+ -> appearance materialization164+ -> final SVG165+```166+167+The renderer owns source interpretation and layout. Later stages preserve diagram geometry while adding safety, semantic paint roles, and optional presentation bounds.168+169+## Artifact stages170+171+| Stage | Contract |172+| --- | --- |173+| Renderer SVG | Output from one identified renderer build. |174+| Canonical SVG | Sanitized SVG with normalized metadata, bounds, and supported semantic roles. |175+| Materialized SVG | Canonical geometry combined with one explicit appearance, palette, and optional frame. |176+177+Materialization does not run the renderer again. Light, dark, transparent, and framed artifacts reuse the same canonical geometry.178+179+Framed appearances may expand the outer view box for standard padding and the frame. They do not reroute connectors or reflow labels.180+181+## Appearance contract182+183+The appearance name is a closed enum:184+185+```text186+raw187+auto-transparent188+light-transparent189+dark-transparent190+auto-framed191+light-framed192+dark-framed193+```194+195+`raw` preserves the safe renderer appearance. It does not promise byte-for-byte preservation because sanitization and deterministic serialization still apply.196+197+Automatic appearances embed both palettes and select one with `prefers-color-scheme`. They do not depend on styles from the embedding page.198+199+Transparent appearances omit the outer canvas. Diagram objects may retain opaque surfaces when those surfaces are required for readable labels.200+201+Framed appearances add a matching canvas, standard padding, and a border. They remain readable independently of the embedding page.202+203+The editor offers only appearances advertised by the active profile. `raw` is always available.204+205+## Capability levels206+207+| Conformance | Meaning | Expected appearance support |208+| --- | --- | --- |209+| `semantic` | Stable renderer meaning maps directly to shared visual roles. | All audited appearances. |210+| `adaptive` | Known structure and neutral paint adapt while authored color remains intact. | All audited appearances. |211+| `presentation-only` | The authored drawing stays unchanged while Diagram.zip owns the outer presentation. | Raw and audited framed appearances. |212+| `raw` | The SVG is safe, but no themed adaptation is claimed. | Raw only. |213+214+An authored non-neutral color may remain unchanged in a semantic or adaptive profile. Normalization does not erase meaningful source styling.215+216+## How renderer versions select a profile217+218+Each engine catalog entry pins a renderer version and an audited normalization profile. Compatibility belongs to that tested pair, not only to the engine name.219+220+HTTP renderers identify their output with these response headers:221+222+| Header | Purpose |223+| --- | --- |224+| `X-Diagram-Engine-Version` | Identifies the underlying engine release. |225+| `X-Renderer-Build` | Identifies the Diagram.zip renderer build. |226+227+Browser renderers provide the same version identity from their catalog entry. Diagram.zip uses this identity before it assigns semantic roles.228+229+An unknown or upgraded renderer build does not inherit an older profile automatically. It falls back to `safe-raw-1`, which supports only `raw`.230+231+This fail-closed behavior prevents rules for one renderer structure from changing unrelated elements in another structure.232+233+Version identifiers are opaque contract values. Consumers should compare complete values and must not infer compatibility from embedded numbers.234+235+The [renderer catalog](https://diagram.zip/render/v1/catalog) reports every engine version, known loss, and active normalization capability.236+237+## Independently versioned contracts238+239+| Contract | Example identifier | Changes when |240+| --- | --- | --- |241+| Canonical schema | `1` | The canonical SVG structure changes incompatibly. |242+| Normalizer | `svg-normalizer-2` | Sanitization, annotation, or serialization behavior changes. |243+| Profile | `neutral-svg-semantic-2` | Renderer recognition or role assignment changes. |244+| Palette | `diagramzip-palette-1` | Materialized role colors change. |245+| Materializer | `svg-materializer-2` | Appearance rules, padding, frame, or output assembly changes. |246+| Renderer | Catalog version and build | Engine output or its integration changes. |247+248+These versions advance independently. A renderer upgrade does not require a schema change, and a palette update does not require new geometry.249+250+Any component that changes pixels or bounds must change the relevant build identifier. Cache identity must include every component that affected the artifact.251+252+## Root SVG metadata253+254+Canonical and materialized SVG expose their active contract through `data-dz-*` attributes on the root element.255+256+| Attribute | Meaning |257+| --- | --- |258+| `data-dz-schema` | Canonical SVG schema. |259+| `data-dz-normalizer` | Normalizer build. |260+| `data-dz-engine` | Renderer engine identifier. |261+| `data-dz-profile` | Selected normalization profile. |262+| `data-dz-palette` | `renderer` for raw SVG, or the selected Diagram.zip palette build. |263+| `data-dz-appearance` | Materialized appearance. |264+| `data-dz-conformance` | Active capability level. |265+| `data-dz-appearances` | Supported non-raw appearances, separated by spaces. |266+| `data-dz-bounds` | Canonical diagram bounds as `x y width height`. |267+| `data-dz-materializer` | Materializer build, present after non-raw materialization. |268+269+Normalized elements may also use `data-dz-fill`, `data-dz-stroke`, and `data-dz-role`. These attributes separate semantic intent from concrete palette values.270+271+```xml272+<svg273+ data-dz-schema="1"274+ data-dz-normalizer="svg-normalizer-2"275+ data-dz-engine="mermaid"276+ data-dz-profile="neutral-svg-semantic-2"277+ data-dz-palette="renderer"278+ data-dz-appearance="raw"279+ data-dz-conformance="adaptive"280+ data-dz-appearances="auto-transparent light-transparent dark-transparent auto-framed light-framed dark-framed"281+ data-dz-bounds="0 0 320 180">282+</svg>283+```284+285+The identifiers above are examples. Inspect the artifact or catalog instead of hard-coding them.286+287+Consumers should treat `data-dz-appearances` as an allowlist. Adding an unsupported value by hand does not create a supported artifact.288+289+## Consumer guarantees290+291+A normalized SVG has these guarantees:292+293+- It is valid, sanitized, deterministic SVG with no unapproved network dependency.294+- It is self-contained after materialization and does not require embedding-page CSS.295+- It preserves renderer geometry, except for presentation bounds added by a frame.296+- It applies palette rules only to elements assigned a supported semantic role.297+- It preserves authored paint when the profile cannot adapt that paint honestly.298+- It rejects unsupported appearance materialization instead of applying heuristic theming.299+300+Cache keys must include source identity, renderer options, renderer builds, schema, normalizer, profile, palette, materializer, and appearance.301+302+Do not key a cache only by source and engine name. That can return artifacts created under an incompatible renderer or presentation contract.303+304+## Upgrade expectations305+306+A renderer upgrade is a new output contract until the representative test corpus passes. The existing profile may then add compatibility, or a new profile may replace it.307+308+Tests cover safety, determinism, raw fidelity, geometry stability, contrast, transparent canvases, frames, authored colors, and hostile resource attempts.309+310+See the [full engineering contract](https://github.com/FelineStateMachine/diagramzip/blob/main/docs/svg-normalization.md) for profile design, semantic roles, validation rules, and caching details.311+312+---313+314+---315+id: sharing316+title: Share a diagram317+description: Share read-only or editable diagram.zip links.318+sidebar_position: 1319+---320+321+# Share a diagram322+323+Save a diagram before you share it. A saved diagram has a stable read link.324+325+The Share dialog contains link controls and privacy controls. Lock, password326+change, and password removal actions stay beside the content they affect.327+328+## Read links329+330+A read link lets a person open the saved diagram. The link has this form:331+332+```text333+https://diagram.zip/d/{alias}334+```335+336+Anyone who has an open read link can view the diagram. Anyone who has an open337+read link can also use the SVG or Markdown embed link.338+339+A read link does not let a person save changes to the saved diagram.340+341+For a locked diagram, the person must also enter the password. The password is342+not part of the read link.343+344+## Edit links345+346+An edit link gives permission to save changes to the alias. It has this form:347+348+```text349+https://diagram.zip/d/{alias}#w={write-capability}350+```351+352+The edit capability is a bearer credential. Anyone who has the complete edit353+link can update the diagram. Share it only with people who should have write354+access.355+356+The browser reads the capability from the URL fragment. The browser then saves357+it for that alias and removes it from the address bar. A copied page URL is358+therefore normally a read link. Copy the edit link from the Share dialog when359+you need to share write access.360+361+Copy actions report success or failure in a short-lived toast above the dialog362+backdrop.363+364+For a locked diagram, an edit link does not replace the password. The person365+needs both the edit capability and the password.366+367+There are no accounts or recovery controls. If you lose the edit capability,368+you cannot update that alias from a new device. If you lose the password for a369+locked diagram, you cannot decrypt it.370+371+## Read-only edits and forks372+373+You can edit a diagram after opening a read link. These edits stay local until374+you save them.375+376+If this browser already has unsaved changes for the link, a local-changes bar377+offers **Restore saved** and **Make a copy**. Restore returns to the shared378+revision. Make a copy forks the local state to a new alias, even when this379+browser also holds write access to the original.380+381+The Save button becomes **Save copy** because you do not have write access to382+the original alias. Save the copy to create a new alias and a new edit link.383+The original diagram does not change.384+385+## Save conflicts386+387+Each saved alias has a revision. The editor checks the revision when it saves.388+389+If another person saved a newer revision first, diagram.zip reports a save390+conflict. Choose one of these actions:391+392+- **Reload saved** discards your local edits and opens the newer saved version.393+- **Save as new** keeps your edits and creates a separate alias.394+395+The editor does not overwrite a newer saved revision without your choice.396+397+## Embeds398+399+The Share dialog provides an SVG image link and a Markdown image link for an400+open saved diagram. These links point to the saved render.401+402+Locked diagrams cannot be embedded. An embed request cannot ask for a password,403+so the server does not return encrypted diagram renders as public images.404+405+Save the diagram again before you share if the Share dialog says that the links406+show an older saved version.407+408+---409+410+---411+id: encryption412+title: Password encryption413+description: Understand password protection for diagram.zip diagrams.414+sidebar_position: 2415+---416+417+# Password encryption418+419+Use a password when a diagram must not be readable by people who only have its420+read link.421+422+## What is encrypted423+424+When you lock a diagram, the browser encrypts these items before it sends them425+to diagram.zip:426+427+- diagram source;428+- diagram type and renderer options;429+- presentation settings;430+- title and description;431+- saved SVG and PNG renders.432+433+The browser decrypts the diagram after you enter the password. The renderer434+can receive the source while it creates a preview. Persistent storage receives435+encrypted data for a locked diagram.436+437+## What the password does438+439+The browser creates a private encryption key for the diagram. The password440+protects that key. The browser uses a new random value for each encrypted item.441+442+The password and the unwrapped encryption key stay in the browser. diagram.zip443+does not receive either value.444+445+The password also protects read access. A person with only the read link sees a446+password prompt. A person with an edit link still needs the password before447+they can read or save the diagram.448+449+## Password changes450+451+Changing the password changes the protection for the private encryption key.452+It does not require the browser to encrypt every stored item again.453+454+Enter the current password before you change or remove password protection.455+456+## Password loss457+458+There is no password reset or account recovery. If you lose the password, you459+cannot decrypt the source, metadata, or saved renders. Keep a secure copy of460+the password when the diagram is important.461+462+## Locked drafts463+464+The editor keeps an open draft in the browser so you can recover recent work.465+It does not write a locked draft to browser storage as plaintext.466+467+For a locked diagram, keep the page open and save the diagram explicitly. A468+locked draft is persisted only after a successful save. If the page closes469+before that save, the browser may not be able to restore the draft.470+471+## Embeds472+473+Locked diagrams cannot use public SVG or Markdown embeds. An embed has no safe474+way to ask for the password. Open the diagram in diagram.zip to enter the475+password and view it.476+477+---478+479+---480+id: working-and-saved-state481+title: Working state and saved state482+description: Understand editor drafts, saved revisions, and persistent diagram data.483+sidebar_position: 3484+---485+486+# Working state and saved state487+488+The editor has a working state and a saved state. They can be different until489+you save.490+491+## Working state492+493+The working state is what you currently see and edit. It includes the diagram494+source, type, renderer options, presentation settings, title, and description.495+496+Source and Details use separate editor tabs. Details is a JSON document that497+contains the title, description, and presentation settings.498+499+Invalid Details JSON remains in the local draft. The editor keeps the last500+valid preview and blocks save, share, privacy, and type changes until it is valid.501+502+When you edit a saved diagram, the working state changes first. The saved503+diagram does not change until you choose **Save**.504+505+For an open diagram, diagram.zip stores the working state as a local browser506+draft. This draft supports recovery on the same browser. It is not a saved507+diagram and other people cannot read it.508+509+An edited anonymous example shows a reset icon. Reset removes its local draft510+and restores the bundled example after confirmation.511+512+When a saved link opens with a different local draft, the editor marks that513+draft as a device-only overlay. Choose **Restore saved** to discard the overlay514+and return to the alias revision, or **Make a copy** to preserve it under a new515+alias. Neither action silently changes the original share link.516+517+For a locked diagram, the editor does not store the working state as plaintext518+in browser storage. Save a locked diagram explicitly to persist it.519+520+Zoom and pan are preview session state, not saved diagram state. Appearance521+changes and Edit or Preview tab switches preserve the current view position.522+523+## Saved state524+525+The saved state is the last version that you saved successfully. It has an526+alias, a revision, and a stable read link.527+528+The Share dialog uses the saved state. If the working state has changes, the529+dialog tells you to save before you share. This prevents you from sharing an530+older version by mistake.531+532+## Persistent data533+534+After a successful save, diagram.zip persists the diagram content and its535+metadata. It can also persist SVG and PNG renders for that saved revision.536+537+Open content is stored as readable diagram data. Locked content and locked538+renders are stored as encrypted data. See [Password encryption](/collaboration/encryption/)539+for the locked diagram rules.540+541+The persisted data belongs to the alias and its current revision. A local draft542+does not replace the persisted data.543+544+## Save flow545+546+The normal flow is:547+548+1. Edit the working state.549+2. Choose **Save**.550+3. diagram.zip stores a new revision.551+4. The saved state becomes the working state.552+553+Saving a new diagram creates an alias and an edit capability. Saving an open554+diagram with an edit capability updates its alias. Saving a read-only diagram555+creates a new alias instead.556+557+## Conflicts558+559+The editor saves against the revision that it last loaded. If that revision is560+no longer current, another person saved the alias first.561+562+The editor then offers **Reload saved** or **Save as new**. Reload replaces the563+working state with the current saved state. Save as new preserves the working564+state in a new alias. diagram.zip does not silently overwrite the other565+person's saved version.566+567+---568+3569 ---4570 id: create-plantuml5571 slug: /create/types/plantuml@@ -60,7 +626,7 @@ sidebar_label: PlantUML
60626 61627 PlantUML supports themes, skin parameters, colors, sprites, and element-specific style rules.62628 63-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.629+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.64630 65631 ## Source controls66632 @@ -146,7 +712,7 @@ sidebar_label: Mermaid
146712 147713 Mermaid supports themes, frontmatter configuration, class definitions, and diagram-specific configuration.148714 149-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.715+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.150716 151717 ## Source controls152718 @@ -234,7 +800,7 @@ sidebar_label: Graphviz
234800 235801 DOT supports graph, node, and edge attributes.236802 237-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.803+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.238804 239805 ## Source controls240806 @@ -321,7 +887,7 @@ sidebar_label: D2
321887 322888 D2 supports themes, shape properties, style blocks, classes, and sketch mode.323889 324-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.890+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.325891 326892 ## Source controls327893 @@ -406,7 +972,7 @@ sidebar_label: C4 PlantUML
406972 407973 C4 PlantUML supports layout macros, tags, legends, and PlantUML style controls.408974 409-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.975+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.410976 411977 ## Source controls412978 @@ -488,7 +1054,7 @@ sidebar_label: BlockDiag
4881054 4891055 BlockDiag supports diagram attributes and per-node or per-edge attributes.4901056 491-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1057+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.4921058 4931059 ## Source controls4941060 @@ -571,7 +1137,7 @@ sidebar_label: SeqDiag
5711137 5721138 SeqDiag supports participant, message, and diagram attributes.5731139 574-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1140+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.5751141 5761142 ## Source controls5771143 @@ -659,7 +1225,7 @@ sidebar_label: ActDiag
6591225 6601226 ActDiag supports lane, action, edge, and diagram attributes.6611227 662-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1228+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.6631229 6641230 ## Source controls6651231 @@ -744,7 +1310,7 @@ sidebar_label: NwDiag
7441310 7451311 NwDiag supports network and host attributes.7461312 747-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1313+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.7481314 7491315 ## Source controls7501316 @@ -829,7 +1395,7 @@ sidebar_label: PacketDiag
8291395 8301396 PacketDiag supports global layout values and field attributes.8311397 832-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1398+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.8331399 8341400 ## Source controls8351401 @@ -913,7 +1479,7 @@ sidebar_label: RackDiag
9131479 9141480 RackDiag supports rack and device attributes.9151481 916-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1482+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.9171483 9181484 ## Source controls9191485 @@ -1000,7 +1566,7 @@ sidebar_label: BPMN
10001566 10011567 BPMN appearance usually comes from BPMN diagram interchange data and renderer defaults.10021568 1003-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1569+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.10041570 10051571 ## Source controls10061572 @@ -1079,7 +1645,7 @@ sidebar_label: Bytefield
10791645 10801646 Bytefield uses drawing-form properties for spans, labels, and layout.10811647 1082-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1648+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.10831649 10841650 ## Source controls10851651 @@ -1164,7 +1730,7 @@ sidebar_label: DBML
11641730 11651731 DBML describes schema structure. It does not define visual presentation.11661732 1167-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1733+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.11681734 11691735 ## Source controls11701736 @@ -1246,7 +1812,7 @@ sidebar_label: Diagrams.net
12461812 12471813 Diagrams.net stores geometry and style values on cells in the XML source.12481814 1249-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1815+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.12501816 12511817 ## Source controls12521818 @@ -1319,7 +1885,7 @@ sidebar_label: Ditaa
13191885 13201886 Ditaa supports shape tags, color tags, dashed lines, and renderer options.13211887 1322-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1888+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.13231889 13241890 ## Source controls13251891 @@ -1412,7 +1978,7 @@ sidebar_label: ERD
14121978 14131979 ERD focuses on the data model. The renderer controls most visual values.14141980 1415-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.1981+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.14161982 14171983 ## Source controls14181984 @@ -1492,7 +2058,7 @@ sidebar_label: Excalidraw
14922058 14932059 Excalidraw stores the style of each element in the JSON source.14942060 1495-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2061+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.14962062 14972063 ## Source controls14982064 @@ -1586,7 +2152,7 @@ sidebar_label: GoAT
15862152 15872153 GoAT takes most geometry from the text. Renderer options control SVG colors and character handling.15882154 1589-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2155+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.15902156 15912157 ## Source controls15922158 @@ -1672,7 +2238,7 @@ sidebar_label: Nomnoml
16722238 16732239 Nomnoml uses hash directives and custom classifier styles.16742240 1675-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2241+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.16762242 16772243 ## Source controls16782244 @@ -1749,7 +2315,7 @@ sidebar_label: Pikchr
17492315 17502316 Pikchr supports dimensions, colors, fills, line widths, and placement controls in the source.17512317 1752-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2318+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.17532319 17542320 ## Source controls17552321 @@ -1829,7 +2395,7 @@ sidebar_label: Structurizr
18292395 18302396 Structurizr supports workspace styles, themes, tags, and automatic layout.18312397 1832-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2398+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.18332399 18342400 ## Source controls18352401 @@ -1911,7 +2477,7 @@ sidebar_label: Svgbob
19112477 19122478 Svgbob takes geometry from the text and supports renderer-level SVG settings.19132479 1914-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2480+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.19152481 19162482 ## Source controls19172483 @@ -1999,7 +2565,7 @@ sidebar_label: Symbolator
19992565 20002566 Symbolator gets structure from hardware source. Renderer options control the title, scale, and output details.20012567 2002-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2568+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.20032569 20042570 ## Source controls20052571 @@ -2086,7 +2652,7 @@ sidebar_label: TikZ
20862652 20872653 TikZ supports colors, line forms, fills, node styles, scopes, and reusable style definitions.20882654 2089-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2655+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.20902656 20912657 ## Source controls20922658 @@ -2166,7 +2732,7 @@ sidebar_label: UMLet
21662732 21672733 UMLet stores position and style commands in the UXF XML source.21682734 2169-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2735+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.21702736 21712737 ## Source controls21722738 @@ -2274,7 +2840,7 @@ sidebar_label: Vega
22742840 22752841 Vega controls presentation through scales, mark encodings, axes, legends, and configuration.22762842 2277-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2843+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.22782844 22792845 ## Source controls22802846 @@ -2364,7 +2930,7 @@ sidebar_label: Vega-Lite
23642930 23652931 Vega-Lite controls presentation through marks, encodings, scales, axes, legends, and configuration.23662932 2367-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.2933+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.23682934 23692935 ## Source controls23702936 @@ -2449,7 +3015,7 @@ sidebar_label: WaveDrom
24493015 24503016 WaveDrom supports source configuration, signal attributes, and a limited set of bundled skins.24513017 2452-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.3018+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.24533019 24543020 ## Source controls24553021 @@ -2535,7 +3101,7 @@ sidebar_label: WireViz
25353101 25363102 WireViz uses YAML properties for connector, cable, wire, and output styles.25373103 2538-Start with the [general presentation settings](/style/presentation). Choose a shared appearance, or use the renderer defaults with custom canvas controls.3104+Start with the [general presentation settings](/style/presentation). Edit shared or raw presentation in Details, and keep renderer-specific styling in Source.25393105 25403106 ## Source controls25413107 @@ -1,6 +1,6 @@
11 # diagram.zip documentation22 3-> Choose the semantic story first, then choose a renderer and source format.3+> Choose the semantic story first. Use Source for notation and Details for metadata and presentation.44 55 - [Diagram routing skill](https://docs.diagram.zip/skills/diagramming/SKILL.md): Select a diagram family from the reader's question.66 - [Machine-readable semantic catalog](https://docs.diagram.zip/diagram-skills.json): Inspect every skill, use case, exclusion, role, and invocation constraint.@@ -97,7 +97,8 @@
9797 9898 ## General pages9999 100-- [General presentation](https://docs.diagram.zip/style/presentation/)100+- [Editor workspace](https://docs.diagram.zip/create/)101+- [Details JSON and presentation](https://docs.diagram.zip/style/presentation/)101102 - [SVG normalization and version contracts](https://docs.diagram.zip/style/svg-normalization/)102103 - [Share a diagram](https://docs.diagram.zip/collaboration/sharing/)103104 - [Password encryption](https://docs.diagram.zip/collaboration/encryption/)@@ -107,5 +108,5 @@
107108 108109 - [diagram-skills.json](https://docs.diagram.zip/diagram-skills.json)109110 - [diagram-types.json](https://docs.diagram.zip/diagram-types.json)110-- [Full renderer text reference](https://docs.diagram.zip/llms-full.txt)111+- [Full documentation text](https://docs.diagram.zip/llms-full.txt)111112 - [Source repository](https://github.com/FelineStateMachine/diagramzip)@@ -23,6 +23,8 @@ Use this model-invokable skill after a diagram is drafted, when a user asks whet
2323 2424 Prefer styles that reinforce meaning: consistent shape roles, restrained color, explicit boundaries, and labels that survive grayscale or color-vision differences. Keep bespoke styling local and documented. Do not let a theme override a formal symbol's meaning or make decorative elements look like data.2525 26+Inspect shared appearances in light and dark output. Test transparent output against light and dark host surfaces.27+2628 ## Prior art2729 2830 For formal diagrams, compare against the relevant [OMG UML](https://www.omg.org/spec/UML), [OMG BPMN](https://www.omg.org/spec/BPMN/2.0.2/), or [C4 notation](https://c4model.com/diagrams/notation) guidance. For flowcharts, consult [ISO 5807](https://www.iso.org/standard/11955.html) where exact symbol conventions matter. Standards are review references; the local renderer catalog determines what diagram.zip can execute.@@ -24,7 +24,15 @@ The same system can be shown as a flow, interaction, boundary, dependency, data
2424 2525 ## Renderer routing2626 27-Common choices include Mermaid for compact general diagrams, PlantUML for UML-oriented notation, C4 PlantUML for C4 views, Graphviz or D2 for graph structure, BPMN for formal process exchange, DBML for relational schemas, and PacketDiag/Bytefield for protocol fields. The complete supported set and syntax links are in the generated `llms.txt` and `apps/docs/data/diagram-types.mjs`. Do not claim a standard is supported merely because a renderer has a similarly named mode: confirm the renderer's actual output and interchange fidelity.27+Common choices include Mermaid for compact general diagrams, PlantUML for UML-oriented notation, C4 PlantUML for C4 views, and Graphviz or D2 for graph structure. BPMN supports formal process exchange, DBML supports relational schemas, and PacketDiag or Bytefield supports protocol fields.28+29+The complete renderer set and syntax links are in [llms.txt](https://docs.diagram.zip/llms.txt) and [diagram-types.json](https://docs.diagram.zip/diagram-types.json). Semantic routing metadata is in [diagram-skills.json](https://docs.diagram.zip/diagram-skills.json).30+31+Do not infer standards support from a similarly named renderer mode. Confirm the renderer's output and interchange fidelity.32+33+## diagram.zip delivery34+35+Keep renderer notation in Source. Use Details only for the title, description, and presentation settings. Follow the [presentation guide](https://docs.diagram.zip/style/presentation/) for the current JSON shape.2836 2937 ## Prior art and standards3038 @@ -1,6 +1,6 @@
11 # Flowchart conventions22 3-ISO 5807:1985, confirmed current in 2019, defines documentation symbols and conventions for data, program, and system flowcharts. Use it as a vocabulary and review aid rather than assuming that a renderer's shape names prove conformance.3+ISO 5807:1985 remains published and defines documentation symbols and conventions for data, program, and system flowcharts. Use it as a vocabulary and review aid. A renderer's shape names do not prove conformance.44 55 Reference: [ISO 5807:1985](https://www.iso.org/standard/11955.html).66 @@ -1,9 +1,8 @@
11 # diagram.zip persistence22 3-Status: implemented locally end to end. The editor, Worker API, D1/R2 model,4-browser encryption, stable render URLs, and conflict/fork/share flows are covered5-by automated tests. Remote Cloudflare resources have not been provisioned or6-deployed.3+Status: implemented end to end. The editor, Worker API, D1/R2 model, browser4+encryption, stable render URLs, and conflict/fork/share flows have automated5+coverage. Production deployment uses the repository release workflow.76 87 ## Product contract98 @@ -192,10 +191,15 @@ Open drafts continue to autosave locally and render after the existing debounce.
192191 They do not write to D1 or R2. Locked drafts are deliberately not written to193192 local storage as plaintext; they persist only when the user explicitly saves.194193 194+The left pane separates diagram Source from schema-validated Details JSON.195+Details owns title, description, and presentation values. Invalid Details text196+remains recoverable while save, share, privacy, and type changes stay blocked.197+195198 - New draft: **Save** creates an alias and changes the browser to its read URL.196199 - Writable alias: **Save** updates with the last revision.197-- Read-only alias: edits form a local fork; **Save as new** creates a new alias.198-- Conflict: offer **Reload remote** or **Save as new**. Never overwrite silently.200+- Anonymous example: the reset icon discards its local draft after confirmation.201+- Read-only alias: edits form a local fork; **Save a copy** creates a new alias.202+- Conflict: offer **Reload saved** or **Save as new**. Never overwrite silently.199203 - Share, open: copy read link, copy edit link, SVG link, or Markdown.200204 - Share, locked: copy password-required read link or password-and-capability edit201205 link. SVG and Markdown embeds are visibly disabled with the explanation that@@ -23,6 +23,8 @@ Use this model-invokable skill after a diagram is drafted, when a user asks whet
2323 2424 Prefer styles that reinforce meaning: consistent shape roles, restrained color, explicit boundaries, and labels that survive grayscale or color-vision differences. Keep bespoke styling local and documented. Do not let a theme override a formal symbol's meaning or make decorative elements look like data.2525 26+Inspect shared appearances in light and dark output. Test transparent output against light and dark host surfaces.27+2628 ## Prior art2729 2830 For formal diagrams, compare against the relevant [OMG UML](https://www.omg.org/spec/UML), [OMG BPMN](https://www.omg.org/spec/BPMN/2.0.2/), or [C4 notation](https://c4model.com/diagrams/notation) guidance. For flowcharts, consult [ISO 5807](https://www.iso.org/standard/11955.html) where exact symbol conventions matter. Standards are review references; the local renderer catalog determines what diagram.zip can execute.@@ -24,7 +24,15 @@ The same system can be shown as a flow, interaction, boundary, dependency, data
2424 2525 ## Renderer routing2626 27-Common choices include Mermaid for compact general diagrams, PlantUML for UML-oriented notation, C4 PlantUML for C4 views, Graphviz or D2 for graph structure, BPMN for formal process exchange, DBML for relational schemas, and PacketDiag/Bytefield for protocol fields. The complete supported set and syntax links are in the generated `llms.txt` and `apps/docs/data/diagram-types.mjs`. Do not claim a standard is supported merely because a renderer has a similarly named mode: confirm the renderer's actual output and interchange fidelity.27+Common choices include Mermaid for compact general diagrams, PlantUML for UML-oriented notation, C4 PlantUML for C4 views, and Graphviz or D2 for graph structure. BPMN supports formal process exchange, DBML supports relational schemas, and PacketDiag or Bytefield supports protocol fields.28+29+The complete renderer set and syntax links are in [llms.txt](https://docs.diagram.zip/llms.txt) and [diagram-types.json](https://docs.diagram.zip/diagram-types.json). Semantic routing metadata is in [diagram-skills.json](https://docs.diagram.zip/diagram-skills.json).30+31+Do not infer standards support from a similarly named renderer mode. Confirm the renderer's output and interchange fidelity.32+33+## diagram.zip delivery34+35+Keep renderer notation in Source. Use Details only for the title, description, and presentation settings. Follow the [presentation guide](https://docs.diagram.zip/style/presentation/) for the current JSON shape.2836 2937 ## Prior art and standards3038 @@ -1,6 +1,6 @@
11 # Flowchart conventions22 3-ISO 5807:1985, confirmed current in 2019, defines documentation symbols and conventions for data, program, and system flowcharts. Use it as a vocabulary and review aid rather than assuming that a renderer's shape names prove conformance.3+ISO 5807:1985 remains published and defines documentation symbols and conventions for data, program, and system flowcharts. Use it as a vocabulary and review aid. A renderer's shape names do not prove conformance.44 55 Reference: [ISO 5807:1985](https://www.iso.org/standard/11955.html).66