konpeki 0.1.0 → 0.1.1

package/README.md

@@ -15,32 +15,15 @@ editable JSON, or use **Present** for a chrome-free presentation.
 Requires **Node.js 24+**, npm, a coding agent that can edit files and run commands,
 and a browser.
 
-For agent-led installation, give your agent [SETUP.md](SETUP.md) and your brief.
-For a manual quickstart:
-
-```sh
-mkdir konpeki-workspace
-cd konpeki-workspace
-npm init -y
-npm install --save-dev konpeki@0.1.0
-cp node_modules/konpeki/slides/introducing-konpeki/composition.json introduction.json
-npm exec --no -- konpeki preview introduction.json
-```
-
-Open the exact URL printed by `preview`. Browser edits save to the composition
-file; valid agent edits appear on the same canvas. In a remote environment, use
-its authenticated preview mechanism rather than sharing a local address.
-
-Open the workspace in your coding agent and ask it to read
-`node_modules/konpeki/SETUP.md`. The installed package includes the authoring skill,
-design guidance and examples; skills inside dependencies may need to be read
-explicitly. Keep your documents outside `node_modules`. Give your brief in the
-agent's prompt field:
+Give your coding agent the public setup URL and your brief. The guide covers
+installation; no repository clone or manual package installation is needed first:
 
 ```text
-Use Konpeki to turn these notes into a three-slide explanation for engineers.
-Make the request flow and failure handling easy to follow. Preserve facts and
-caveats. Save editable composition JSON, then render, inspect and fix the result.
+Read https://raw.githubusercontent.com/vcfgdev/konpeki/main/SETUP.md
+and set up Konpeki in this workspace.
+Turn these notes into a three-slide explanation for engineers. Make the request
+flow and failure handling easy to follow. Preserve facts and caveats. Save editable composition
+JSON, open the preview, then render, inspect and fix the result.
 
 [Paste notes or provide source files.]
 ```
@@ -50,6 +33,24 @@ approval” when you want a checkpoint. Supply a visual direction or leave it op
 [authoring modes](AUTHORING.md#authoring-mode) provide defaults without requiring
 you to choose fonts, colors or layouts first.
 
+The package includes the authoring skill, design guidance and examples—no GitHub
+clone is required. Keep your documents outside `node_modules`.
+
+## Try an editable example
+
+For a manual start, install [Konpeki from npm](https://www.npmjs.com/package/konpeki)
+in your workspace (run `npm init -y` first in a new, empty directory):
+
+```sh
+npm install --save-dev konpeki@0.1.1
+cp node_modules/konpeki/slides/introducing-konpeki/composition.json introduction.json
+npm exec --no -- konpeki preview introduction.json
+```
+
+Open the exact URL printed by `preview`. Browser edits save to your copied file;
+valid agent edits appear on the same canvas. In a remote environment, use its
+authenticated preview mechanism rather than sharing a local address.
+
 ## Examples and guides
 
 - [Example gallery](slides/README.md): 18 fictional examples and an editable

package/SETUP.md

@@ -25,7 +25,7 @@ agent. An in-app browser is convenient but not required.
   reuse the same CLI version. Do not edit files inside `node_modules`.
 
 ```sh
-npm install --save-dev konpeki@0.1.0
+npm install --save-dev konpeki@0.1.1
 ```
 
 In a new empty directory, run `npm init -y` first. Run subsequent commands from

package/docs/development.md

@@ -101,6 +101,54 @@ commands against a composition outside the installed package. Do not publish
 until that isolated preview works. Publish the tested tarball rather than
 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`
+(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
+to validate a composition and build the packaged canvas. It stages that same
+tarball for maintainer approval; it does not publish directly. Browser review
+remains a pre-release responsibility.
+
+Before the first tag release, configure **Trusted publishing → GitHub Actions**
+in the `konpeki` package settings on npmjs.com:
+
+- Organization or user: `vcfgdev`
+- Repository: `konpeki`
+- Workflow filename: `publish.yml`
+- Environment name: leave empty
+- Leave **Allow npm publish** unchecked (staged publishing only)
+
+The workflow uses GitHub-hosted runners and OIDC (`id-token: write`); no npm
+token secret is needed. Staged publishing requires npm 11.15.0 or newer and
+Node 22.14.0 or newer; the pinned toolchain meets both requirements.
+npm generates provenance automatically for public repositories;
+private repositories do not receive provenance.
+
+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
+```
+
+Replace `0.1.1` with the new version. `0.1.0` is already published and 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,
+use an authenticated local CLI:
+
+```sh
+mise exec -- npm stage list konpeki
+mise exec -- npm stage view <stage-id>
+mise exec -- npm stage approve <stage-id>
+```
+
+Approval makes the version public. Reject an incorrect staged release instead
+of approving it (`npm stage reject <stage-id>`).
+
 ## Verification
 
 ```sh
@@ -117,6 +165,11 @@ node scripts/check-canvas.mjs http://localhost:4318 .amp/in/artifacts
 node scripts/check-pages.mjs http://localhost:4318 .amp/in/artifacts/pages
 ```
 
+For the Build it lifecycle, `node scripts/check-build.mjs` starts its own
+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.
+
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "konpeki",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A shared editable canvas for agent-made visuals",
   "license": "Apache-2.0",
   "repository": {

package/src/app/App.tsx

@@ -72,7 +72,6 @@ export function App() {
   const [error, setError] = useState(loaded.error ?? "");
   const [notice, setNotice] = useState<{
     message: string;
-    undoableFor?: Draft;
   }>();
   const [toastClosing, setToastClosing] = useState(false);
   const [leftCollapsed, setLeftCollapsed] = useState(false);
@@ -80,7 +79,6 @@ export function App() {
   const [rightView, setRightView] = useState<RightPanelView>("settings");
   const [vectorEditRequest, setVectorEditRequest] = useState(0);
   const [presenting, setPresenting] = useState(false);
-  const [buildBusy, setBuildBusy] = useState(false);
   const [exportBusy, setExportBusy] = useState(false);
   const [vectorSelection, setVectorSelection] = useState<{
     componentId: string;
@@ -105,7 +103,6 @@ export function App() {
         ) ? current.present.activeSlideId : document.slides[0].id,
         selected: undefined,
       }));
-      showNotice("Agent changes loaded. Undo restores the previous composition.");
     },
     onNotice: showNotice,
     onError: setError,
@@ -144,7 +141,7 @@ export function App() {
   }, [draft, blocked, loaded.example, loaded.fileSession]);
   useEffect(() => {
     if (!notice) return;
-    const timer = window.setTimeout(() => setToastClosing(true), 5000);
+    const timer = window.setTimeout(() => setToastClosing(true), 3000);
     return () => window.clearTimeout(timer);
   }, [notice]);
   useEffect(() => {
@@ -157,7 +154,7 @@ export function App() {
   }, [toastClosing]);
   useEffect(() => {
     function keydown(event: KeyboardEvent) {
-      if (presenting) return;
+      if (presenting || fileSession.building) return;
       const modifier = event.metaKey || event.ctrlKey;
       const target = event.target;
       const editable =
@@ -213,10 +210,10 @@ export function App() {
     }
     window.addEventListener("keydown", keydown);
     return () => window.removeEventListener("keydown", keydown);
-  }, [draft, presenting, selected, vectorSelection]);
-  function showNotice(message: string, undoableFor?: Draft) {
+  }, [draft, presenting, selected, vectorSelection, fileSession.building]);
+  function showNotice(message: string) {
     setToastClosing(false);
-    setNotice({ message, undoableFor });
+    setNotice({ message: message.replace(/\.$/, "") });
   }
   function updateDraft(
     next: Draft,
@@ -283,15 +280,11 @@ export function App() {
       activeSlideId: nextActiveSlideId,
       selected: id === slide.id ? undefined : selected,
     });
-    showNotice("Page deleted.", next);
+    showNotice("Page deleted.");
   }
   function finishEdit() {
     setHistory(finishHistoryEdit);
   }
-  function performUndo() {
-    focusAfterHistory.current = true;
-    setHistory(undoHistory);
-  }
   function performRedo() {
     focusAfterHistory.current = true;
     setHistory(redoHistory);
@@ -419,20 +412,16 @@ export function App() {
         : selected;
     focusAfterHistory.current = true;
     updateDraft(next, { selected: nextSelected });
-    showNotice("Component deleted.", next);
+    showNotice("Component deleted.");
   }
   async function requestBuild() {
-    setBuildBusy(true);
     try {
       const instruction = selected
         ? "Review the selected component in context and build it from the current saved composition."
         : "Review the current slides and build them from the current saved composition.";
-      if (!await fileSession.build(instruction, slide.id, selected)) return;
-      showNotice("Build request sent. The agent will reread this saved revision.");
+      await fileSession.build(instruction, slide.id, selected);
     } catch (requestError) {
       showNotice(requestError instanceof Error ? requestError.message : "Could not send the build request.");
-    } finally {
-      setBuildBusy(false);
     }
   }
   async function openComposition(file: File) {
@@ -454,7 +443,7 @@ export function App() {
       selected: undefined,
     });
     setTitleError(false);
-    showNotice("Editable composition opened. Undo restores the previous document.", parsed.document);
+    showNotice("Editable composition opened. Undo restores the previous document.");
   }
   function present() {
     const validation = validateComposition(draft);
@@ -524,7 +513,7 @@ export function App() {
         </div>
       )}
       <div
-        className={`workspace ${leftCollapsed ? "left-collapsed" : ""} ${rightCollapsed ? "right-collapsed" : ""}`}
+        className={`workspace ${fileSession.building ? "is-building" : ""} ${leftCollapsed ? "left-collapsed" : ""} ${rightCollapsed ? "right-collapsed" : ""}`}
         aria-hidden={presenting || undefined}
         inert={presenting || undefined}
         onDragOver={(event) => {
@@ -533,6 +522,10 @@ export function App() {
           event.dataTransfer.dropEffect = "copy";
         }}
         onDrop={(event) => {
+          if (fileSession.building) {
+            event.preventDefault();
+            return;
+          }
           const file = event.dataTransfer.files[0];
           if (!file) return;
           event.preventDefault();
@@ -555,11 +548,12 @@ export function App() {
           exporting={exportBusy}
           onPresent={present}
           fileStatus={loaded.fileSession ? fileSession.status : undefined}
-          building={buildBusy}
+          building={fileSession.building}
           onBuild={loaded.fileSession ? () => { void requestBuild(); } : undefined}
           onSelectTool={() => selectComponent()}
           onComponentTool={useComponentTool}
         />
+        <div className="editor-content" inert={fileSession.building} aria-busy={fileSession.building}>
         <LeftPanel
           draft={draft}
           activeSlideId={slide.id}
@@ -654,6 +648,16 @@ export function App() {
           }
           onEditEnd={finishEdit}
         />
+        </div>
+        {fileSession.building && (
+          <div className="stage build-loading" role="status" aria-live="polite">
+            <div className="build-loading-card">
+              <div className="build-loading-track" aria-hidden="true" />
+              <strong>Waiting for agent</strong>
+              <span>Your canvas will refresh when changes arrive.</span>
+            </div>
+          </div>
+        )}
       </div>
       {presenting && (
         <Presentation
@@ -668,26 +672,6 @@ export function App() {
         <span role="status" aria-live="polite">
           {notice?.message}
         </span>
-        {notice?.undoableFor === draft && (
-          <button
-            type="button"
-            onClick={() => {
-              performUndo();
-              showNotice("Change undone.");
-            }}
-          >
-            Undo
-          </button>
-        )}
-        {notice && (
-          <button
-            type="button"
-            aria-label="Dismiss notification"
-            onClick={() => setToastClosing(true)}
-          >
-            ×
-          </button>
-        )}
       </div>
     </>
   );

package/src/components/InspectorPanel.tsx

@@ -502,7 +502,6 @@ export function InspectorPanel({
       {component.customVisual && (
         <fieldset className="custom-visual-summary">
           <legend>Agent visual</legend>
-          <p>{component.customVisual.description}</p>
           <dl>
             <div>
               <dt>Source</dt>
@@ -523,11 +522,11 @@ export function InspectorPanel({
               <dd>{component.customVisual.fit ?? "contain"}</dd>
             </div>
           </dl>
-          <p className="field-help">
-            {component.customVisual.format === "vector"
-              ? "Select the visual and press Enter or choose Edit elements. Double-click an element to edit its text or attributes here. Only top-level line endpoints have drag handles; paths use attribute controls."
-              : "This legacy SVG is an opaque compatibility fallback. Ask an agent to convert it to editable vector elements."}
-          </p>
+          {component.customVisual.format !== "vector" && (
+            <p className="field-help">
+              This legacy SVG is an opaque compatibility fallback. Ask an agent to convert it to editable vector elements.
+            </p>
+          )}
           {vectorVisual && (
             <>
               <Field label="Vector element">

package/src/components/WorkspaceChrome.tsx

@@ -100,6 +100,7 @@ export function WorkspaceChrome({
             aria-describedby={titleError ? "title-error" : undefined}
             name="composition-title"
             autoComplete="off"
+            disabled={building}
             value={title}
             onChange={(event) => onTitle(event.target.value, "title")}
             onBlur={onEditEnd}
@@ -140,7 +141,7 @@ export function WorkspaceChrome({
           className="icon-only"
           aria-label="Export PNG"
           title="Export active page as PNG"
-          disabled={exporting}
+          disabled={exporting || building}
           onClick={onExportPNG}
         >
           <svg viewBox="0 0 24 24" aria-hidden="true">
@@ -148,7 +149,7 @@ export function WorkspaceChrome({
             <path d="m7 14 3.5-4 3 3 2-2 2.5 3M12 16v5m-3-3 3 3 3-3" />
           </svg>
         </button>
-        <button type="button" onClick={onPresent}>
+        <button type="button" onClick={onPresent} disabled={building}>
           <svg viewBox="0 0 24 24" aria-hidden="true">
             <rect x="3" y="4" width="18" height="12" rx="2" />
             <path d="M12 16v5m-4 0h8M10 7l5 3-5 3Z" />
@@ -158,19 +159,20 @@ export function WorkspaceChrome({
         {onBuild && (
           <button
             type="button"
-            className="primary"
+            className={`primary build-button ${building ? "building" : ""}`}
             disabled={fileStatus !== "saved" || building}
+            aria-busy={building}
             onClick={onBuild}
           >
             <svg viewBox="0 0 24 24" aria-hidden="true">
               <path d="m5 19 10-10 3 3L8 22Zm10-10 2-2 3 3-2 2M5 3v6M2 6h6m10-5v4m-2-2h4" />
             </svg>
-            {building ? "Building…" : "Build it"}
+            <span>{building ? "Building…" : "Build it"}</span>
           </button>
         )}
       </div>
 
-      <nav className="component-dock" aria-label="Canvas tools">
+      <nav className="component-dock" aria-label="Canvas tools" inert={building}>
         <button
           type="button"
           className={!selectedKind ? "active" : ""}

package/src/lib/use-file-session.ts

@@ -26,6 +26,9 @@ export function useFileSession(
 ) {
   const token = fileSessionToken();
   const [status, setStatus] = useState<FileStatus>(enabled ? "loading" : "saved");
+  const [building, setBuilding] = useState(false);
+  const buildPending = useRef(false);
+  const submittingBuild = useRef(false);
   const callbacksRef = useRef(callbacks);
   callbacksRef.current = callbacks;
   const draftRef = useRef(draft);
@@ -72,10 +75,12 @@ export function useFileSession(
     if (!enabled || !token) return;
     let cancelled = false;
     const timer = window.setInterval(() => {
-      if (!state.current.ready || state.current.drain) return;
+      if (!state.current.ready || state.current.drain || submittingBuild.current) return;
+      const revision = state.current.revision;
       void loadFileSession(token).then((remote) => {
-        if (cancelled || remote.revision === state.current.revision) return;
+        if (cancelled || state.current.drain || submittingBuild.current || revision !== state.current.revision || remote.revision === revision) return;
         if (canonicalJSON(draftRef.current) !== state.current.savedJSON) {
+          finishBuild();
           setStatus("conflict");
           callbacksRef.current.onNotice(
             "The file changed elsewhere. Neither version was overwritten.",
@@ -89,8 +94,14 @@ export function useFileSession(
         };
         setStatus("saved");
         callbacksRef.current.onExternalChange(remote.document);
+        finishBuild();
       }).catch(() => {
-        if (!cancelled) setStatus("error");
+        if (cancelled || submittingBuild.current || revision !== state.current.revision) return;
+        setStatus("error");
+        if (buildPending.current) {
+          finishBuild();
+          callbacksRef.current.onNotice("Could not load the agent result. Check the local file service.");
+        }
       });
     }, 1000);
     return () => {
@@ -99,6 +110,11 @@ export function useFileSession(
     };
   }, [enabled, token]);
 
+  function finishBuild() {
+    buildPending.current = false;
+    setBuilding(false);
+  }
+
   function save(next: Draft): Promise<string | undefined> {
     if (!token || !state.current.ready) return Promise.resolve(undefined);
     const serialized = canonicalJSON(next);
@@ -146,17 +162,30 @@ export function useFileSession(
     slideId: string,
     componentId?: string,
   ) {
-    if (!token) return false;
-    const revision = await save(draftRef.current);
-    if (!revision) return false;
-    await sendBuildRequest(token, {
-      revision,
-      instruction,
-      slideId,
-      ...(componentId ? { componentId } : {}),
-    });
-    return true;
+    if (!token || buildPending.current) return false;
+    buildPending.current = true;
+    submittingBuild.current = true;
+    setBuilding(true);
+    try {
+      const revision = await save(draftRef.current);
+      if (!revision) {
+        finishBuild();
+        return false;
+      }
+      await sendBuildRequest(token, {
+        revision,
+        instruction,
+        slideId,
+        ...(componentId ? { componentId } : {}),
+      });
+      return true;
+    } catch (error) {
+      finishBuild();
+      throw error;
+    } finally {
+      submittingBuild.current = false;
+    }
   }
 
-  return { status, build };
+  return { status, build, building };
 }

package/src/styles/chrome.css

@@ -146,12 +146,12 @@
 }
 
 .action-island button.primary {
-  background: #202020;
-  color: white;
+  background: white;
+  color: var(--ui-text);
 }
 
 .action-island button.primary:hover:not(:disabled) {
-  background: #383838;
+  background: var(--ui-hover);
 }
 
 .action-island button.primary:disabled {
@@ -159,6 +159,54 @@
   color: var(--ui-muted);
 }
 
+.action-island .build-button {
+  position: relative;
+  overflow: hidden;
+  justify-content: center;
+  flex: 1;
+  white-space: nowrap;
+}
+
+.action-island button.build-button.building {
+  background: linear-gradient(110deg, #155e75, #2449aa, #7535a5, #a82d62, #155e75);
+  background-size: 300% 100%;
+  color: white;
+  opacity: 1;
+  cursor: wait;
+  animation: build-colors 4s linear infinite;
+}
+
+.build-button.building::after,
+.build-loading-track::after {
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(90deg, transparent, #ffffff50, transparent);
+  transform: translateX(-100%);
+  animation: build-sweep 1.8s ease-in-out infinite;
+  content: "";
+}
+
+.build-button.building::after {
+  top: auto;
+  height: 3px;
+}
+
+@keyframes build-colors {
+  to { background-position: 150% 0; }
+}
+
+@keyframes build-sweep {
+  to { transform: translateX(100%); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .action-island button.build-button.building,
+  .build-button.building::after,
+  .build-loading-track::after {
+    animation: none;
+  }
+}
+
 .action-island button svg {
   flex: none;
   width: 18px;

package/src/styles/feedback.css

@@ -7,47 +7,49 @@
   transform-origin: center top;
   display: none;
   align-items: center;
-  gap: 14px;
-  background: #252525;
-  color: white;
-  padding: 10px 12px 10px 18px;
-  border-radius: 6px;
+  gap: 12px;
+  background: var(--ui-surface);
+  color: var(--ui-text);
+  border: 1px solid var(--ui-border);
+  box-shadow: 0 4px 16px #0000000a, 0 1px 3px #00000008;
+  padding: 10px 14px;
+  border-radius: 12px;
   font-size: 13px;
-  max-width: 80vw;
+  line-height: 1.5;
+  width: max-content;
+  max-width: min(520px, max(240px, calc(100vw - 744px)), calc(100vw - 40px));
   z-index: 50;
 }
+.toast > [role="status"] {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
 .toast.visible {
   display: flex;
-  animation: toast-expand 360ms cubic-bezier(0.16, 1, 0.3, 1) both;
+  animation: toast-enter 180ms ease-out both;
 }
 .toast.visible.closing {
   pointer-events: none;
-  animation: toast-expand 280ms cubic-bezier(0.4, 0, 0.8, 0.2) reverse both;
-}
-.toast button {
-  background: transparent;
-  border-color: #707070;
-  color: white;
-  padding: 5px 10px;
+  animation: toast-exit 180ms ease-in both;
 }
-.toast button:hover:not(:disabled) {
-  background: #444;
-}
-@keyframes toast-expand {
-  0% {
+@keyframes toast-enter {
+  from {
     opacity: 0;
-    transform: translate(-50%, -22px) scale(0.72, 0.4);
+    transform: translate(-50%, -6px);
   }
-  62% {
+  to {
     opacity: 1;
-    transform: translate(-50%, 5px) scale(1.04, 1.08);
-  }
-  80% {
-    transform: translate(-50%, -1px) scale(0.99, 0.97);
+    transform: translate(-50%, 0);
   }
-  100% {
+}
+@keyframes toast-exit {
+  from {
     opacity: 1;
-    transform: translate(-50%, 0) scale(1);
+    transform: translate(-50%, 0);
+  }
+  to {
+    opacity: 0;
+    transform: translate(-50%, -6px);
   }
 }
 .recovery {

package/src/styles/shell.css

@@ -208,6 +208,45 @@
 .workspace.right-collapsed .stage {
   padding-right: 96px;
 }
+.editor-content {
+  display: contents;
+}
+.is-building .canvas {
+  opacity: 0.25;
+  filter: blur(2px);
+}
+.build-loading {
+  z-index: 20;
+  pointer-events: none;
+}
+.build-loading-card {
+  display: grid;
+  gap: 10px;
+  width: min(320px, 100%);
+  padding: 24px;
+  border: 1px solid var(--ui-border);
+  border-radius: 14px;
+  background: var(--ui-surface);
+  box-shadow: var(--ui-shadow);
+  text-align: center;
+}
+.build-loading-card strong {
+  font-size: 14px;
+  font-weight: 500;
+}
+.build-loading-card span {
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--ui-muted);
+}
+.build-loading-track {
+  position: relative;
+  overflow: hidden;
+  height: 3px;
+  margin-bottom: 8px;
+  border-radius: 2px;
+  background: linear-gradient(90deg, #155e75, #2449aa, #7535a5, #a82d62);
+}
 .slide-wrap {
   width: 100%;
   max-width: min(1200px, calc((100vh - 270px) * var(--page-ratio)));