konpeki 0.2.0 → 0.3.1

package/slides/introducing-konpeki/README.md

@@ -1,54 +1,44 @@
 # Introducing Konpeki
 
-A six-slide English introduction for first-time users. Defaults to Plex on paper
-with theme-linked colors and fonts; deck appearance can switch palettes and
-Paper/Night without repainting vector elements. Uses the default authoring mode.
-
-1. **Meet Konpeki** — one shared canvas for people and coding agents.
-2. **A round-trip workflow** — draft, download, agent revision, open and present.
-3. **Five semantic components** — Text block, Diagram, Chart, Image and Table.
-4. **Keep the detail editable** — stable vector elements inside their owners.
-5. **What works today** — capabilities alongside practical boundaries.
-6. **Try a real brief** — setup and an example request.
+A six-page introduction covering creation, shared editing, components, revision
+notes, browser/file sessions and a first brief. Uses default authoring mode and
+Precision Paper with theme-linked colors and fonts.
 
 ## Open and revise
 
-Run `pnpm dev` from the repository root and open
-`?example=introducing-konpeki` in the application. Select **Present** for viewing.
-The example preview does not autosave: use **Download** to keep changes, then
-**Open** the saved JSON from the ordinary canvas for browser-local autosave.
+Open the [playground example](https://vcfgdev.github.io/konpeki/?example=introducing-konpeki)
+and select **Present**. Edits save to a separate browser-local copy; use
+**Browser → Download JSON** to keep them. **Reset example** restores the bundled
+version, so download your work first. Browser storage is not a backup or agent sync.
+
+For agent revisions, follow [setup](../../SETUP.md) and open a copy of
+[composition.json](composition.json) in a file-backed preview. Notes, **Build it**
+and **Copy prompt** work there, not in the standalone playground. See the
+[canvas workflow](../../docs/workflow.md) for handoff details.
+
+The JSON is the editable source: double-click text to edit it; diagrams contain
+editable vector elements. [author.ts](author.ts) reconstructs the original deck:
 
-[composition.json](composition.json) is the authoritative editable deck. Each
-slide contains semantic components. Ordinary text uses native content and typography
-fields; diagrams and custom specimens keep editable vector elements. Double-click
-ordinary text to edit it directly; Content intent remains separate agent guidance.
-This is not a second React deck runtime or a collection of page images.
+```sh
+mise exec -- node slides/introducing-konpeki/author.ts
+```
 
-[author.ts](author.ts) records the initial drawing instructions. Running
-`node slides/introducing-konpeki/author.ts` validates and regenerates the JSON;
-it **replaces manual canvas revisions**, so do not rerun it over revised work.
-See [the public brief excerpt](PROMPT.md) and [source facts / provenance](SOURCE.md).
+Run from the repository root. **This overwrites canvas edits.**
+[Brief](PROMPT.md) · [Sources](SOURCE.md) · [Reviewed screenshots](screenshots/)
 
 ## Review
 
-- `pnpm check`, `pnpm test` (91 tests), `pnpm build`, `git diff --check`: passed.
-- Inspected all six actual canvas renders at 1920×1080 and 1024×768, DPR2.
-- Browser text bounds checked after font loading: no text outside its component
-  viewport at either size. Visible navigation exercised across all six pages.
-- Enlarged essential notes and clarified placeholder wording after first review.
-- Follow-up alignment review: removed renderer insets that displaced vector
-  titles and body text. Added `review.mjs` to verify each authored viewport maps
-  to its component rectangle within 0.5 screen pixels at both review sizes.
-  Run `node slides/introducing-konpeki/review.mjs` with the dev server running
-  and `agent-browser` installed; inspect its captures after the assertions pass.
-- Native-text verification: all six slides passed text/viewport checks in Plex
-  Paper, Precision Night and Editorial Paper, at both sizes (36 states).
-  Pass output directory, theme label and mode after the base URL to `review.mjs`.
-  `node scripts/check-themes.mjs` exercises all eight palettes in both modes,
-  fixed overrides, overflow warnings, linking, undo/redo, Prompt guidance and
-  autosave/reload/presentation. Literal imported artwork is intentionally fixed.
-- Final reviewed presentation captures: [screenshots](screenshots/).
-- Chart values are illustrative; diagrams are explanatory artwork, not screenshots.
-- No PDF/PPTX export, native mobile or cross-application fidelity was tested.
+With a dev/preview server and `agent-browser`, run from the repository root:
+
+```sh
+mise exec -- node slides/introducing-konpeki/review.mjs <preview-url> /tmp/konpeki-intro Precision paper
+```
+
+The script checks text bounds and vector alignment at 1920×1080 and 1024×768,
+DPR2. Repeat with `Precision night` and `Editorial paper`, then inspect captures.
+An optional final font ID overrides the palette's default, e.g. `Green paper plex-serif`.
+These 36 states passed the original visual review, alongside validation, typecheck,
+tests and build. Browser review does not verify agent-client installation,
+PDF/PPTX, mobile, reduced motion, focus styling or cross-application fidelity.
 
 ![Title slide](screenshots/page-1.png)

package/slides/introducing-konpeki/SOURCE.md

@@ -1,20 +1,19 @@
 # Source facts and provenance
 
-This is a factual introduction to Konpeki, not a fictional customer case study.
+Product claims come from repository documentation, not a customer case study.
 
 | Claim | Repository evidence |
 | --- | --- |
-| One canvas for human drafts, agent output, revision and presentation | ../../README.md; ../../AGENTS.md |
-| Composition JSON is authoritative; imported JSX never executes | ../../composition/README.md; ../../AUTHORING.md |
-| Five top-level kinds: Text block, Diagram, Chart, Image, Table | ../../composition/types.ts |
-| Open / Download / Present workflow; browser-local storage | ../../README.md; ../../src/lib/storage.ts |
-| Stable vector IDs, text/attribute edits, ordering, deletion and undo/redo | ../../README.md; ../../composition/vector.ts |
-| Standard component illustrations are drafts, not data or image uploads | ../../README.md |
-| Node 24+, pnpm; repository distribution, no Konpeki account/backend required | ../../README.md; ../../package.json |
+| Covers, social graphics, charts, diagrams and presentations share one canvas | [Product](../../README.md); [authoring](../../AUTHORING.md) |
+| Skill-led creation; init optional; Node.js 24+, npm, file/command access and a browser required | [User setup](../../SETUP.md) |
+| Browser and agent edit the same JSON; file sessions support notes, Build it and Copy prompt | [File-backed workflow](../../docs/workflow.md#file-backed-editing-with-an-agent) |
+| Text block, Diagram, Chart, Image and Table; editable vectors with stable IDs | [Contract](../../composition/README.md); [types](../../composition/types.ts) |
+| Direct text, shape and layout editing with undo/redo | [Operations](../../composition/document.ts) |
+| Diagram, Chart and Table defaults are structural drafts; finished artwork needs source data | [Exports](../../docs/workflow.md#documents-and-exports); [fidelity rules](../../AUTHORING.md#requirements) |
+| Playground: independent local copies, JSON import/download, blank/reset, PNG and Present; no agent sync, connected AI or cloud storage | [Hosting](../../docs/development.md#development-server-and-demo-hosting); [storage](../../src/lib/storage.ts); [controls](../../src/components/WorkspaceChrome.tsx) |
 
-The architecture drawings, vector selection example and component specimens are
-original explanatory artwork for this deck, not product screenshots. The tiny
-chart uses explicitly labeled illustrative values, not measured product data.
-No third-party image assets or customer claims are used. IBM Plex Sans comes from
-the repository's Fontsource dependency. No PDF/PPTX or cross-application fidelity
-is claimed.
+Drawings are original explanatory artwork, not screenshots. Chart values and
+the announcement brief are illustrative, not product measurements or customer
+results. No third-party images are used. Precision defaults to bundled Noto Sans;
+text follows the selected font roles. See the [review scope](README.md#review)
+for verification limits.

package/slides/introducing-konpeki/author.ts

@@ -1,6 +1,7 @@
-// Initial authoring source. composition.json is the editable deck of record.
+// Authoring source. composition.json is the editable deck of record.
 // Re-running this script replaces it; preserve canvas revisions before rebuilding.
 import { writeFile } from "node:fs/promises";
+import { canonicalJSON } from "../../composition/compile.ts";
 import { createComponent } from "../../composition/document.ts";
 import { validateComposition } from "../../composition/validate.ts";
 import {
@@ -24,6 +25,7 @@ function arrow(id: string, x: number, y: number, end: number) {
 }
 function component(id: string, kind: CompositionComponent["kind"], x: number, y: number, width: number, height: number, description: string, elements: VectorElement[]): CompositionComponent {
   const base = createComponent(kind, 1);
+  if (base.kind === "diagram" || base.kind === "chart") base.appearance.selection = "explicit";
   return { ...base, id, slotIds: [`${id}-content`], preferredRect: { x, y, width, height }, intent: description,
     customVisual: { format: "vector", viewBox: { x: 0, y: 0, width, height }, fit: "contain", description, elements } };
 }
@@ -52,40 +54,40 @@ function heading(id: string, title: string, subtitle: string) {
 const slides: CompositionSlide[] = [];
 slides.push(slide("introduction", "Meet Konpeki", "What is Konpeki?", [
   copy("brand", 112, 140, 820, ["Konpeki"], 112, blue, 600),
-  copy("promise", 112, 328, 960, ["A shared slide canvas", "for people and coding agents."], 56, ink, 500),
-  copy("summary", 112, 548, 870, ["Sketch the idea. Generate the detail.", "Keep revising the same document."], 36, muted),
+  copy("promise", 112, 328, 960, ["Create clear visuals", "with your coding agent."], 56, ink, 500),
+  copy("summary", 112, 548, 870, ["Bring a brief. Get an editable result.", "Keep revising the same document."], 36, muted),
   component("shared-canvas", "diagram", 1090, 185, 700, 590, "A single editable composition contains a headline, diagram and supporting text; people and agents revise it.", [
     rect("canvas-frame", 8, 25, 670, 395),
-    text("canvas-title", "An idea, made clear", 45, 93, 36, ink, 500),
+    text("canvas-title", "From brief to visual", 45, 93, 36, ink, 500),
     path("headline-rule", "M45 120H640", line, 2),
     rect("source-node", 50, 183, 160, 90, blue), rect("result-node", 310, 183, 320, 90, blue),
-    text("source-label", "Idea", 98, 239, 28), text("result-label", "Explanation", 382, 239, 28),
+    text("source-label", "Brief", 98, 239, 28), text("result-label", "Editable visual", 374, 239, 28),
     arrow("connection", 228, 228, 292),
     path("body-lines", "M50 323H395M50 351H525", line, 8),
     text("document-label", "composition.json", 178, 484, 32, blue, 500),
     text("participants", "Human edits + agent revisions", 116, 548, 28, muted),
   ]),
-  copy("intro-note", 112, 870, 1696, ["For technical explanations, product stories and decision decks."], 34),
+  copy("intro-note", 112, 870, 1696, ["Covers, social graphics, charts, diagrams and presentations."], 34),
 ]));
 
-slides.push(slide("workflow", "A round-trip workflow", "How do a person and an agent work together?", [
-  ...heading("workflow", "A handoff that comes back to the canvas", "The agent works on the document you can keep editing."),
-  component("roundtrip", "diagram", 112, 342, 1696, 470, "Draft on the canvas, download composition JSON, ask a coding agent to revise it, then open the returned JSON and present. Further edits repeat this loop.", [
+slides.push(slide("workflow", "Create and revise together", "How do a person and an agent work together?", [
+  ...heading("workflow", "Start with a brief. Keep editing the result.", "In the agent-opened editor, you and your agent edit the same file."),
+  component("roundtrip", "diagram", 112, 342, 1696, 470, "Share a brief and materials. The agent creates a visual and opens its file-backed preview. Edit that canvas, then ask for revisions in the same conversation. The agent updates the same file; the loop returns to editing, not a new brief.", [
     ...[0, 1, 2, 3].flatMap((index) => {
       const x = index * 438;
       return [text(`number-${index}`, `0${index + 1}`, x, 48, 26, blue, 500),
-        text(`step-${index}`, ["Draft", "Download", "Agent revises", "Open + present"][index], x, 122, 42, ink, 500),
-        text(`detail-a-${index}`, ["Place components.", "Save the editable", "Return a completed", "Review the result."][index], x, 190, 29, muted),
-        text(`detail-b-${index}`, ["Describe the intent.", "composition JSON.", "composition JSON.", "Make the next edit."][index], x, 234, 29, muted),
+        text(`step-${index}`, ["Brief", "Generate", "Edit", "Revise"][index], x, 122, 42, ink, 500),
+        text(`detail-a-${index}`, ["Share your materials.", "Agent creates a visual.", "Edit the open canvas.", "Ask in the same chat."][index], x, 190, 29, muted),
+        text(`detail-b-${index}`, ["Describe the result.", "Opens its file preview.", "Review the details.", "Agent updates that file."][index], x, 234, 29, muted),
         ...(index < 3 ? [arrow(`handoff-${index}`, x + 338, 109, x + 398)] : [])];
     }),
-    path("revision-loop", "M1510 285V365H115V285M103 299L115 285L127 299", blue),
-    text("loop-label", "Revisions stay in the same editable format", 490, 431, 32, blue),
+    path("revision-loop", "M1510 285V365H991V285M979 299L991 285L1003 299", blue),
+    text("loop-label", "Both edit the same composition.json", 490, 431, 32, blue),
   ]),
-  copy("workflow-note", 112, 870, 1696, ["Use your coding agent alongside Konpeki; bring its returned JSON back to the canvas."], 34, ink),
+  copy("workflow-note", 112, 870, 1696, ["Prefer to sketch first? Add a component, describe its intent, then choose Build it."], 34, ink),
 ]));
 
-slides.push(slide("components", "Five semantic components", "What can a slide contain?", [
+slides.push(slide("components", "Five semantic components", "What can a page contain?", [
   ...heading("components", "Five components. One composition.", "Each component keeps its meaning, outer geometry and editable interior."),
   component("text-specimen", "text-block", 112, 360, 296, 360, "Text block: headlines, body text, captions and footnotes.", [
     text("label", "Text block", 0, 40, 38, ink, 500), text("sample", "Aa", 0, 166, 96, blue),
@@ -111,14 +113,14 @@ slides.push(slide("components", "Five semantic components", "What can a slide co
     text("label", "Table", 0, 40, 38, ink, 500),
     text("col-a", "Stage", 0, 120, 26, ink, 500), text("col-b", "Owner", 157, 120, 26, ink, 500),
     path("rules", "M0 136H285M0 190H285M0 244H285", line, 2),
-    text("row-a", "Draft", 0, 174, 25), text("row-a-owner", "Human", 157, 174, 25), text("row-b", "Revise", 0, 228, 25), text("row-b-owner", "Agent", 157, 228, 25),
+    text("row-a", "Create", 0, 174, 25), text("row-a-owner", "Agent", 157, 174, 25), text("row-b", "Review", 0, 228, 25), text("row-b-owner", "You", 157, 228, 25),
     text("detail", "Structured detail", 0, 317, 28, muted),
   ]),
-  copy("component-note", 112, 876, 1696, ["Draft previews express intent. Agents return completed artwork as editable vectors."], 34, ink),
+  copy("component-note", 112, 848, 1696, ["Diagram, Chart and Table previews are structural drafts.", "Give the agent real data and sources for finished artwork."], 32, ink),
 ]));
 
 slides.push(slide("editing", "Keep the detail editable", "What remains editable after an agent finishes?", [
-  ...heading("editing", "The detail stays editable", "Revise a label, a path or a group without replacing the whole slide."),
+  ...heading("editing", "Keep editing—or ask your agent", "Change text, shapes and layout directly. Undo and redo stay available."),
   component("editable-diagram", "diagram", 112, 340, 980, 475, "Explanatory illustration: a selected Review node inside its owning Diagram component. The shape keeps stable ID review-node.", [
     rect("owner", 5, 5, 965, 390), text("owner-label", "Diagram · review-flow", 35, 53, 27, muted),
     rect("draft", 55, 158, 220, 120), rect("review-node", 385, 158, 220, 120, blue), rect("present", 715, 158, 220, 120),
@@ -127,37 +129,37 @@ slides.push(slide("editing", "Keep the detail editable", "What remains editable
     ...[[380,153],[600,153],[380,273],[600,273]].map(([x,y], i) => rect(`handle-${i}`,x,y,10,10,blue)),
     text("stable-id", "Selected element: review-node", 36, 450, 32, blue),
   ]),
-  copy("editing-actions-title", 1210, 343, 580, ["Change the part that matters"], 35, ink, 500),
-  copy("editing-actions", 1210, 440, 580, ["Edit text and attributes.", "Reorder sibling elements.", "Delete a shape or a group.", "Undo and redo your changes."], 31, muted),
-  copy("editing-note", 112, 885, 1696, ["Composition JSON owns the structure. Imported JSX never executes in the canvas."], 34, ink),
+  copy("editing-actions-title", 1210, 343, 580, ["Ask for a targeted revision"], 35, ink, 500),
+  copy("editing-actions", 1210, 440, 580, ["Select a component or element.", "Add a Revision note in Notes.", "Choose Build it to submit.", "Agent revises the same file."], 31, muted),
+  copy("editing-note", 112, 852, 1696, ["Notes and Build it are available in the agent-opened editor, not the browser playground.", "Build it cannot wake an idle agent. Use Copy prompt to resume it."], 32, ink),
 ]));
 
-slides.push(slide("today", "What works today", "What should a first-time user expect?", [
-  ...heading("today", "An editable workflow, with clear boundaries", "Use the canvas for drafting, revision and presentation today."),
-  copy("available-heading", 112, 350, 790, ["Available now"], 42, blue, 500),
-  copy("available-1", 112, 451, 790, ["Arrange slides and semantic components.", "Open and download composition JSON."], 33),
-  copy("available-2", 112, 605, 790, ["Revise vector text, shapes and paths.", "Present with the same canvas renderer."], 33),
-  copy("available-3", 112, 790, 790, ["Browser-local drafts.", "No Konpeki account or backend required."], 32, ink),
-  copy("limits-heading", 1020, 350, 788, ["Know the boundaries"], 42, ink, 500),
-  copy("limits-1", 1020, 451, 788, ["Standard previews are placeholders.", "They do not load data or image files."], 33),
-  copy("limits-2", 1020, 605, 788, ["Your coding agent supplies the output.", "Review its facts, layout and caveats."], 33),
-  copy("limits-3", 1020, 790, 788, ["Desktop-first editing; storage is local.", "No PDF/PPTX fidelity claim."], 32, ink),
+slides.push(slide("today", "Browser or agent editor", "What can I do here, and what needs a coding agent?", [
+  ...heading("today", "Try the browser. Continue with your agent.", "The same editable format, with different saving and generation paths."),
+  copy("available-heading", 112, 350, 790, ["Browser playground"], 42, blue, 500),
+  copy("available-1", 112, 451, 790, ["Edit an example or start blank.", "Import editable composition JSON."], 33),
+  copy("available-2", 112, 605, 790, ["Saved only in this browser.", "No connected agent or cloud sync."], 33),
+  copy("available-3", 112, 790, 790, ["Download JSON to keep your work.", "Export PNG or use Present."], 32, ink),
+  copy("limits-heading", 1020, 350, 788, ["With your coding agent"], 42, ink, 500),
+  copy("limits-1", 1020, 451, 788, ["The agent creates and revises visuals.", "Its preview saves to a local JSON file."], 33),
+  copy("limits-2", 1020, 605, 788, ["Bring downloaded JSON to your agent.", "Continue in its file-backed editor."], 33),
+  copy("limits-3", 1020, 790, 788, ["Playground and file copies do not sync.", "Review generated facts and visuals."], 32, ink),
 ]));
 
 slides.push(slide("start", "Try a real brief", "How do I start?", [
-  ...heading("start", "Bring a brief. Build an editable deck.", "Start with one real explanation you need to give."),
-  copy("setup-heading", 112, 350, 710, ["Open the project"], 40, ink, 500),
+  ...heading("start", "Install the skill. Bring a real brief.", "Ask for a cover, social graphic, chart, diagram or presentation."),
+  copy("setup-heading", 112, 350, 710, ["Install the Konpeki skill"], 40, ink, 500),
   copy("repository", 112, 435, 850, ["github.com/vcfgdev/konpeki"], 38, blue, 500),
-  copy("commands", 112, 543, 840, ["pnpm install --frozen-lockfile", "pnpm dev"], 34),
-  copy("requirements", 112, 696, 780, ["Node.js 24+ · pnpm", "A coding agent · a browser"], 34, ink),
-  copy("brief-heading", 1020, 350, 788, ["Give your agent a concrete brief"], 40, ink, 500),
-  copy("brief", 1020, 450, 788, ["“Explain this system to a new engineer.", "Show the request flow and failure path.", "Preserve the source facts and caveats.", "Return an editable composition JSON.”"], 31),
-  copy("next-step", 1020, 708, 788, ["Open the result. Make one revision.", "Then present it."], 34, blue, 500),
-  copy("closing", 112, 906, 1696, ["This presentation is itself an editable Konpeki composition."], 30, muted),
+  copy("commands", 112, 543, 840, ["Use your agent’s skill installer.", "Choose skills/konpeki in the repo."], 34),
+  copy("requirements", 112, 696, 780, ["Node.js 24+ · npm", "An agent with file + command access", "A browser for the editable preview"], 32, ink),
+  copy("brief-heading", 1020, 350, 788, ["Then give it one sentence"], 40, ink, 500),
+  copy("brief", 1020, 450, 788, ["“Use Konpeki to turn these launch", "notes into a product announcement.”"], 35),
+  copy("next-step", 1020, 696, 788, ["Need an empty canvas? Ask for init.", "A creation brief selects generate."], 32, blue, 500),
+  copy("closing", 112, 906, 1696, ["Attach your materials; the agent opens and checks the editable result. No separate init needed."], 30, muted),
 ]));
 
-const document: CompositionDocument = { schema: compositionSchema, title: "Introducing Konpeki", authoringMode: "default", theme: { id: "plex", mode: "paper" }, slides };
+const document: CompositionDocument = { schema: compositionSchema, title: "Introducing Konpeki", authoringMode: "default", theme: { id: "precision", mode: "paper" }, slides };
 const result = validateComposition(document);
 if (!result.ok) throw new Error(JSON.stringify(result.issues, null, 2));
-await writeFile(new URL("./composition.json", import.meta.url), JSON.stringify(result.document, null, 2) + "\n");
+await writeFile(new URL("./composition.json", import.meta.url), canonicalJSON(result.document) + "\n");
 console.log(`Authored ${slides.length} editable slides.`);