konpeki 0.1.1 → 0.3.0

package/docs/development.md

@@ -29,13 +29,71 @@ pnpm dev
 For a production preview, run `pnpm build` then `pnpm preview`. The build produces
 a static site in `dist` for a root or subdirectory. Use
 `?example=introducing-konpeki` or `?example=custom-visual` to open a bundled editable
-example. Example links do not autosave; open a composition in a file-backed
-session to preserve edits.
+example. Each example has an isolated browser-local working copy that survives
+reload. The Browser menu supports JSON import/download, starting blank and
+resetting the example. These actions never replace another example or the normal
+local draft. Invalid stored data remains untouched until an explicit reset.
+
+Deploy only the static `dist` output for the public playground, not a file-session
+server. Imported documents stay in that browser; there is no account, cloud sync,
+AI generation or Build/notes handoff in standalone mode. Downloaded JSON can be
+opened in a file-backed session with a coding agent. Browser storage is not a
+backup. Hosting shares bundled examples, not private drafts or an AI service.
+No deployment is automatic. In a remote environment, expose a review server
+through its authenticated preview mechanism, not a loopback address.
+
+The source CLI's `preview` chooses the next available port if its default is
+occupied. An explicit `--port <number>` fails rather than silently changing the
+requested port; `--port 0` asks the OS for a free port. `--json` prints one readiness
+record with `type`, `compositionPath` and the exact session-bearing `url` after
+listening. Treat that URL as a capability, not public logging data. This is a
+startup signal, not proof that the browser loaded the right composition.
+
+### GitHub Pages
+
+The public playground is hosted at
+[vcfgdev.github.io/konpeki](https://vcfgdev.github.io/konpeki/?example=introducing-konpeki).
+The example query opens the introduction; the root URL opens the ordinary local
+draft. Each visitor's edits stay in their own browser, not in the deployed site.
+
+`.github/workflows/pages.yml` deploys only when explicitly dispatched on `main`:
 
-Hosting shares bundled examples, not private drafts, arbitrary documents or an
-AI service. No deployment is automatic. In a remote environment, expose the
-server through its authenticated preview mechanism; a local address is not a
-shareable URL.
+```sh
+gh workflow run pages.yml --repo vcfgdev/konpeki --ref main
+```
+
+The workflow uses the pinned mise/pnpm toolchain, runs typecheck and tests, builds
+with the Pages base path, and uploads only `dist`. The deployment job publishes
+that artifact to the `github-pages` environment. Repository **Settings → Pages →
+Source** must be **GitHub Actions**. Ordinary pushes run CI but do not redeploy;
+package releases remain separate. Inspect the public example after deployment,
+including reload, fonts, editing, JSON download and Present.
+
+Existing example working copies survive deployments. Download any edits before
+choosing **Browser → Reset example** to load a newly published example.
+
+## Skill and plugin packaging
+
+`skills/konpeki/` is the canonical portable skill. The repo's
+`.agents/skills/konpeki` symlink enables local discovery without a second
+copy. The root Agent Plugins `plugin.json` and repo marketplace expose the same
+skill to compatible Codex clients; no MCP, hook or hosted AI is involved. Review
+native-client installation separately from the npm smoke test.
+
+The skill dispatches `init` (open only) and `generate` (create/revise, including
+implicit setup). These are agent modes, not CLI subcommands. Its portable
+`scripts/prepare-document.mjs` validates through the resolved CLI and exclusively
+creates a blank file, or validates an existing file without rewriting it. The
+bundled `assets/blank.json` matches `initialDraft(true)` in
+`composition/document.ts`; onboarding tests enforce that contract. Keep scripts
+and assets when copying the skill. No TypeScript import from `node_modules` is
+needed, so a copied skill also supports the existing published runtime.
+
+Its `scripts/ensure-runtime.mjs` pins the release runtime. It performs
+no installation without `--install`, and never updates project dependencies.
+When preparing a new release, deliberately update its pin and the plugin version
+together with the package version after testing the target runtime. The current
+pin is 0.3.0; local CLI/playground changes do not republish that npm version.
 
 ## Implementation reference
 
@@ -78,7 +136,8 @@ trusted local React source; never use it on untrusted JSX. It rejects unsupporte
 SVG elements rather than silently flattening them. Review converted typography
 and geometry in the browser; conversion is not a fidelity guarantee.
 The bundled `?example=react-page-migration` preview uses the same format.
-Example previews do not autosave; use a file-backed session to save edits.
+Its working copy autosaves in that browser. Download JSON or use a file-backed
+session to retain edits outside browser storage.
 
 ## Package contents
 
@@ -103,7 +162,7 @@ rebuilding during publication. Packing locally does not publish anything.
 
 ## Tag releases
 
-`.github/workflows/publish.yml` stages releases on bare version tags such as `0.1.1`
+`.github/workflows/publish.yml` stages releases on bare version tags such as `0.2.1`
 (no `v` prefix). The tag must equal `package.json`'s version.
 The workflow installs the mise toolchain and frozen dependencies, runs typecheck,
 tests, build and package checks, then installs a tarball in an isolated directory
@@ -130,11 +189,12 @@ After updating the package version, completing release checks and pushing the
 release commit, explicitly create and push its matching tag:
 
 ```sh
-git tag 0.1.1
-git push origin 0.1.1
+VERSION=0.2.1
+git tag "$VERSION"
+git push origin "$VERSION"
 ```
 
-Replace `0.1.1` with the new version. `0.1.0` is already published and cannot be
+Replace `0.2.1` with the version in `package.json`. Published versions cannot be
 republished. Pushing a matching tag submits the tested package to npm's staging
 area. After the workflow succeeds, review the release in npmjs.com's **Staged
 Packages** tab and click **Approve**, completing 2FA to publish it. Alternatively,
@@ -170,6 +230,10 @@ disposable file session. It checks pending requests, agent refresh, failure
 recovery and reduced motion, and captures the affected states. Add an output
 directory and `--record` to also record the animation.
 
+`node scripts/check-notes.mjs` checks page/vector note scopes, draft isolation,
+reload persistence, CLI claim/finish, clarification and cancellation in a disposable
+file-backed browser session. It accepts a screenshot directory as its first argument.
+
 These checks exercise all five component kinds, empty slides, JSON round trips,
 vector editing/history and fitted line dragging. They capture editor and
 presentation states at two sizes; inspect the images because assertions alone

package/docs/workflow.md

@@ -1,9 +1,16 @@
 # Canvas workflow
 
-Start with the [quickstart](../README.md#start-in-your-coding-agent) and give your
-coding agent a brief in its prompt field. Keep the skill with the project:
-copying `SKILL.md` alone does not install Konpeki. Skill discovery varies by
-agent; there is no universal `/konpeki` command.
+Start with [Use with your agent](../README.md#use-with-your-agent) and give your
+coding agent a brief in its prompt field. Install the complete skill directory;
+its bootstrap script finds or installs the runtime separately. Skill discovery
+varies by agent: Codex CLI/IDE uses `$konpeki`, while the standalone Claude Code
+skill uses `/konpeki`. Other clients may use skill selection or natural language.
+`init` opens a blank or existing file-backed editor without generating; `generate`
+creates or revises a visual, opens its preview and inspects it, with setup implicit.
+A creation brief without a mode selects generate. Follow-up reviews continue the
+same document without repeating a command. These are skill modes, not terminal
+subcommands. **Build it** is an optional revision handoff, not a required first-run
+step; opening the editor does not start a review listener.
 
 ## Documents and exports
 
@@ -49,13 +56,55 @@ An agent waiting for a person's revision request runs:
 npm exec --no -- konpeki wait slides/my-visual/composition.json
 ```
 
-In the file-backed canvas, **Build it** saves the composition and submits the
-exact revision, active page and optional selected component. `wait` prints that
-machine-readable request and exits. It does not launch or wake an agent itself.
-The listening agent must reread the named composition, preserve unrelated human
-edits, validate, render and inspect its revision before returning. Browser-local
-drafts and hosted examples do not expose **Build it** because no local agent owns
-their files.
+In the file-backed canvas, select a component or an inner vector element and
+write a **Revision note** in the left panel's **Notes** tab. With nothing selected, the note targets
+the page. **Add note** saves feedback without starting a build; add notes to several
+targets, then choose **Build it** to submit them together. Numbered canvas pins
+return to their note and selection. Pins and notes never appear in presentations
+or PNG exports. Direct text, geometry and attribute edits still save normally.
+
+**Build it** saves the composition and submits its exact revision, selected page,
+component and optional vector-element ID, plus all unresolved notes. Without notes,
+it requests a build from the saved composition and selected scope as before.
+`wait` atomically claims one submitted request, marks it working, prints the
+machine-readable v2 request and exits. It does not launch or wake an agent.
+Until claimed, the canvas asks you to contact your coding agent and offers
+**Copy prompt** for the handoff. “Agent working” means claimed, not a live
+agent heartbeat. Only one request per document can be active. Connection errors
+keep an active request locked until completion or cancellation.
+
+The agent must reread the named composition and preserve newer human edits.
+Follow each note's target IDs, not just the active page; never silently retarget
+a deleted element. After validating, rendering and inspecting all requested
+changes, explicitly finish using the ID returned by `wait`:
+
+```sh
+npm exec --no -- konpeki finish slides/my-visual/composition.json <request-id> --message "Updated and checked"
+```
+
+Only this acknowledgement resolves the submitted notes and unlocks editing.
+File changes alone do not complete the request; explicit no-op completion is
+valid when the requested result is already present. If blocked, finish with
+`--status needs-clarification --message "What needs clarification?"` or
+`--status failed --message "What failed"`. Notes stay unresolved for a retry.
+Do not mark a partly applied batch done. **Cancel request** unlocks the editor
+and keeps notes, but cannot stop an agent process; stop that agent before retrying.
+
+Feedback is stored next to the document as `composition.json.review.json`, separate
+from artwork and exports. Retain that file with the composition when moving work.
+Browser reloads and preview restarts preserve notes and request status. To inspect
+or recover an already claimed request after an interruption, run:
+
+```sh
+npm exec --no -- konpeki request slides/my-visual/composition.json
+```
+
+Coordinate with the previous worker before resuming; `wait` does not claim an
+already working request a second time. Do not edit the sidecar manually while a
+preview or agent is updating it. Existing v1 temporary requests are not migrated;
+finish them before upgrading, then resubmit if needed. Browser-local drafts and
+hosted examples do not expose revision notes or **Build it** because no local
+agent owns their files.
 
 Browser screenshots do not establish PDF/PPTX editability, font embedding or
 cross-application fidelity. Inspect every requested export separately.

package/index.html

@@ -4,10 +4,26 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#ffffff" />
+    <link rel="icon" type="image/png" sizes="128x128" href="/src/assets/konpeki-mark.png" />
     <meta
       name="description"
-      content="An editable canvas for agent-made visuals. Create a single explanation or a whole presentation, then revise it together."
+      content="Try Konpeki's editable canvas. Edit an example, create a page, export PNG or download editable JSON. No account needed; changes stay in your browser."
     />
+    <meta property="og:type" content="website" />
+    <meta property="og:site_name" content="Konpeki" />
+    <meta property="og:title" content="Konpeki — Browser playground" />
+    <meta property="og:description" content="Try Konpeki's editable canvas. Edit an example, create a page, export PNG or download editable JSON. No account needed; changes stay in your browser." />
+    <meta property="og:url" content="https://vcfgdev.github.io/konpeki/?example=introducing-konpeki" />
+    <meta property="og:image" content="https://vcfgdev.github.io/konpeki/og.png" />
+    <meta property="og:image:type" content="image/png" />
+    <meta property="og:image:width" content="1280" />
+    <meta property="og:image:height" content="640" />
+    <meta property="og:image:alt" content="Konpeki — Create clear visuals with your coding agent. Blue brush mark and editable canvas illustrations." />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="Konpeki — Browser playground" />
+    <meta name="twitter:description" content="Try Konpeki's editable canvas. Edit an example, create a page, export PNG or download editable JSON. No account needed; changes stay in your browser." />
+    <meta name="twitter:image" content="https://vcfgdev.github.io/konpeki/og.png" />
+    <meta name="twitter:image:alt" content="Konpeki — Create clear visuals with your coding agent. Blue brush mark and editable canvas illustrations." />
     <title>Konpeki</title>
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "konpeki",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "A shared editable canvas for agent-made visuals",
   "license": "Apache-2.0",
   "repository": {
@@ -20,13 +20,19 @@
   "files": [
     "AGENTS.md",
     "AUTHORING.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
     "SETUP.md",
     "docs/workflow.md",
     "docs/development.md",
-    ".agents/skills/authoring-visuals/SKILL.md",
+    "plugin.json",
+    "skills/konpeki/SKILL.md",
+    "skills/konpeki/scripts/*.mjs",
+    "skills/konpeki/assets/blank.json",
     "runtime/konpeki.mjs",
     "index.html",
     "vite.config.ts",
+    "public/og.png",
     "src/main.tsx",
     "src/app/*.tsx",
     "src/components/*.tsx",
@@ -72,12 +78,14 @@
     "@nivo/sankey": "0.99.0",
     "@xmldom/xmldom": "0.9.12",
     "ajv": "^8.20.0",
+    "proper-lockfile": "4.1.2",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "vite": "^8.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/proper-lockfile": "4.1.4",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.5",
     "typescript": "^5.9.3"

package/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "konpeki",
+  "version": "0.3.0",
+  "description": "Create editable visuals with your coding agent.",
+  "repository": "https://github.com/vcfgdev/konpeki",
+  "license": "Apache-2.0",
+  "extensions": {
+    "com.openai": {
+      "interface": {
+        "displayName": "Konpeki",
+        "shortDescription": "Create editable visuals with your coding agent",
+        "category": "Productivity",
+        "defaultPrompt": [
+          "Use Konpeki to turn these launch notes into a product announcement.",
+          "Use Konpeki to create a cover for this article.",
+          "Use Konpeki to turn this data into a chart for a presentation."
+        ]
+      }
+    }
+  }
+}