konpeki 0.2.0 → 0.3.1

package/src/components/WorkspaceChrome.tsx

@@ -1,4 +1,4 @@
-import type { RefObject } from "react";
+import { useEffect, useRef, useState, type ReactNode, type RefObject } from "react";
 import type { CompositionComponent } from "../../composition/types.ts";
 import { componentLabels } from "../lib/model.ts";
 import mark from "../assets/konpeki-mark.png";
@@ -33,8 +33,8 @@ function DockIcon({
       ) : kind === "diagram" ? (
         <>
           <rect x="3" y="5" width="6" height="5" rx="1" />
-          <rect x="15" y="14" width="6" height="5" rx="1" />
-          <path d="M9 8h6v8M12 13l3 3 3-3" />
+          <rect x="15" y="16" width="6" height="5" rx="1" />
+          <path d="M9 8h9v8m-2.5-2.5L18 16l2.5-2.5" />
         </>
       ) : kind === "image" ? (
         <>
@@ -68,11 +68,14 @@ export function WorkspaceChrome({
   building,
   buildState,
   onBuild,
+  browserTools,
   onSelectTool,
   onComponentTool,
   leftCollapsed,
   onToggleLeftPanel,
+  children,
 }: {
+  children: ReactNode;
   leftCollapsed: boolean;
   onToggleLeftPanel: () => void;
   title: string;
@@ -88,14 +91,48 @@ export function WorkspaceChrome({
   building: boolean;
   buildState?: "ready" | "working";
   onBuild?: () => void;
+  browserTools?: {
+    example: boolean;
+    saveMessage: string;
+    onImportJSON: (file: File) => void;
+    onDownloadJSON: () => void;
+    onStartBlank: () => void;
+    onReset: () => void;
+  };
   onSelectTool: () => void;
   onComponentTool: (kind: CompositionComponent["kind"]) => void;
 }) {
+  const browserMenu = useRef<HTMLDetailsElement>(null);
+  const [browserMenuOpen, setBrowserMenuOpen] = useState(false);
+  const importInput = useRef<HTMLInputElement>(null);
+  function closeBrowserMenu(restoreFocus = true) {
+    const menu = browserMenu.current;
+    if (!menu?.open) return;
+    setBrowserMenuOpen(false);
+    if (restoreFocus) menu.querySelector("summary")?.focus();
+  }
+  useEffect(() => {
+    if (leftCollapsed) closeBrowserMenu(false);
+  }, [leftCollapsed]);
+  useEffect(() => {
+    function dismissOutside(event: Event) {
+      if (event.target instanceof Node && !browserMenu.current?.contains(event.target)) {
+        closeBrowserMenu(false);
+      }
+    }
+    document.addEventListener("pointerdown", dismissOutside);
+    document.addEventListener("focusin", dismissOutside);
+    return () => {
+      document.removeEventListener("pointerdown", dismissOutside);
+      document.removeEventListener("focusin", dismissOutside);
+    };
+  }, []);
   return (
     <>
+      <div className={`left-sidebar${leftCollapsed ? " collapsed" : ""}`}>
       <header className="document-island" aria-label="Document controls">
         <img src={mark} alt="Konpeki" />
-        <label className="document-title">
+        <label className="document-title" inert={leftCollapsed}>
           <span className="sr-only">Composition title</span>
           <input
             ref={titleRef}
@@ -114,22 +151,21 @@ export function WorkspaceChrome({
             Enter a title.
           </span>
         )}
-        {fileStatus && fileStatus !== "saved" && (
+        {fileStatus && (
           <span
             className={`file-status ${fileStatus}`}
             role="status"
             aria-live="polite"
-            title={fileStatus === "conflict"
-              ? "The file changed elsewhere while this browser has edits."
-              : undefined}
+            title={fileStatus === "saved" ? "Saved to file" : fileStatus === "saving" ? "Saving to file" : fileStatus === "loading" ? "Opening file" : "Changes are not saved — see the recovery notice"}
           >
-            {fileStatus === "loading" ? "Opening"
+            <span className="sr-only">{fileStatus === "saved" ? "Saved" : fileStatus === "loading" ? "Opening"
               : fileStatus === "saving" ? "Saving"
-              : fileStatus === "conflict" ? "Conflict" : "Save error"}
+              : fileStatus === "conflict" ? "Conflict" : "Save error"}</span>
           </span>
         )}
         <button type="button" className="panel-toggle"
           aria-label={leftCollapsed ? "Expand left panel" : "Collapse left panel"}
+          aria-expanded={!leftCollapsed}
           onClick={onToggleLeftPanel}>
           <svg className="panel-collapse-icon" viewBox="0 0 24 24" aria-hidden="true">
             <rect x="3" y="4" width="18" height="16" rx="2" />
@@ -138,6 +174,10 @@ export function WorkspaceChrome({
         </button>
       </header>
 
+      <div className="editor-content" inert={building} aria-busy={building}>
+        {children}
+      </div>
+
       <div className="action-island" aria-label="Document actions" inert={leftCollapsed}>
         <button
           type="button"
@@ -158,6 +198,80 @@ export function WorkspaceChrome({
             <path d="M12 16v5m-4 0h8M10 7l5 3-5 3Z" />
           </svg>
         </button>
+        {browserTools && (
+          <details className="browser-menu" ref={browserMenu} open={browserMenuOpen} onKeyDown={(event) => {
+            if (event.key === "Escape" && browserMenu.current?.open) {
+              event.preventDefault();
+              event.stopPropagation();
+              closeBrowserMenu();
+            }
+          }}>
+            <summary onClick={(event) => {
+              event.preventDefault();
+              setBrowserMenuOpen(open => !open);
+            }}>
+              Demo Mode
+              <svg viewBox="0 0 16 16" aria-hidden="true"><path d="m4 10 4-4 4 4" /></svg>
+            </summary>
+            <div className="browser-menu-popover" role="region" aria-label="Demo Mode" inert={!browserMenuOpen}>
+              <div className="browser-menu-intro">
+                <strong>Demo Mode</strong>
+                <p>
+                  Explore the canvas here. No agent connection or file sync.{" "}
+                  <span role="status">{browserTools.saveMessage}</span>
+                </p>
+              </div>
+              <div className="browser-menu-actions">
+                <button type="button" onClick={() => importInput.current?.click()}>
+                  Import
+                </button>
+                <input
+                  ref={importInput}
+                  hidden
+                  type="file"
+                  accept="application/json,.json"
+                  aria-label="Choose composition JSON"
+                  onChange={(event) => {
+                    const file = event.target.files?.[0];
+                    event.target.value = "";
+                    if (!file) return;
+                    closeBrowserMenu();
+                    browserTools.onImportJSON(file);
+                  }}
+                />
+                <button type="button" onClick={() => {
+                  closeBrowserMenu();
+                  browserTools.onDownloadJSON();
+                }}>
+                  Export
+                </button>
+                <button type="button" className="secondary" onClick={() => {
+                  closeBrowserMenu();
+                  browserTools.onStartBlank();
+                }}>
+                  Start blank
+                </button>
+                <button type="button" className="secondary" onClick={() => {
+                  closeBrowserMenu();
+                  browserTools.onReset();
+                }}>
+                  {browserTools.example ? "Reset example" : "Reset local draft"}
+                </button>
+              </div>
+              <div className="browser-agent-handoff">
+                <strong>Continue with an agent</strong>
+                <p>Export the JSON file, then ask your coding agent to open it with Konpeki.</p>
+                <a
+                  href="https://github.com/vcfgdev/konpeki/blob/main/SETUP.md"
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  Setup guide
+                </a>
+              </div>
+            </div>
+          </details>
+        )}
         {onBuild && (
           <button
             type="button"
@@ -171,6 +285,7 @@ export function WorkspaceChrome({
           </button>
         )}
       </div>
+      </div>
 
       <nav className="component-dock" aria-label="Canvas tools" inert={building}>
         <button

package/src/components/ui.tsx

@@ -1,4 +1,98 @@
-import { useId, type ReactNode } from "react";
+import { useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+/** Retain the last content while CSS transitions out; hidden notices are inert. */
+export function FeedbackNotice({ kind, children, tone = "neutral", onDismiss, onPauseChange }: {
+  kind: "toast" | "recovery";
+  children: ReactNode;
+  tone?: "neutral" | "error";
+  onDismiss?: () => void;
+  onPauseChange?: (paused: boolean) => void;
+}) {
+  const visible = Boolean(children);
+  const [last, setLast] = useState({ children, tone });
+  if (visible && (children !== last.children || tone !== last.tone)) setLast({ children, tone });
+  return <div className={`feedback-notice ${kind}${visible ? " visible" : ""}${last.tone === "error" ? " error" : ""}`}
+    inert={!visible} aria-hidden={!visible} role={kind === "recovery" && visible ? "alert" : undefined}
+    onMouseEnter={() => onPauseChange?.(true)} onMouseLeave={() => onPauseChange?.(false)}
+    onFocus={() => onPauseChange?.(true)} onBlur={event => { if (!event.currentTarget.contains(event.relatedTarget)) onPauseChange?.(false); }}>
+    {kind === "toast" ? <span role={visible ? last.tone === "error" ? "alert" : "status" : undefined}
+      aria-live={visible ? last.tone === "error" ? "assertive" : "polite" : "off"}>{last.children}</span> : last.children}
+    {onDismiss && last.children && <button type="button" className="toast-dismiss" aria-label="Dismiss notification" onClick={onDismiss}>×</button>}
+  </div>;
+}
+
+/** Keep incomplete input out of the document, without silently correcting it. */
+export function NumberField({ label, name, value, min, max, step = 1, unit, onCommit, onEditEnd }: {
+  label: string;
+  name?: string;
+  value: number;
+  min: number;
+  max: number;
+  step?: number;
+  unit?: string;
+  onCommit: (value: number) => void;
+  onEditEnd: () => void;
+}) {
+  const [text, setText] = useState(String(value));
+  const [error, setError] = useState("");
+  const [showError, setShowError] = useState(false);
+  const [position, setPosition] = useState({ top: 0, left: 0 });
+  const input = useRef<HTMLInputElement>(null);
+  const id = useId();
+  useEffect(() => { setText(String(value)); setError(""); }, [value]);
+  useLayoutEffect(() => {
+    if (!error || !showError) return;
+    function place() {
+      const rect = input.current!.getBoundingClientRect();
+      const panel = input.current!.closest(".right-panel")!.getBoundingClientRect();
+      const beside = panel.left >= 276;
+      setPosition({ top: Math.max(8, Math.min(beside ? rect.top : rect.bottom + 6, window.innerHeight - 80)), left: beside ? panel.left - 268 : Math.max(8, Math.min(rect.left, window.innerWidth - 268)) });
+      if (rect.bottom < panel.top + 58 || rect.top > panel.bottom) setShowError(false);
+    }
+    function focus(event: FocusEvent) {
+      if (event.target !== input.current) setShowError(false);
+    }
+    place();
+    window.addEventListener("resize", place);
+    window.addEventListener("scroll", place, true);
+    document.addEventListener("focusin", focus);
+    return () => {
+      window.removeEventListener("resize", place);
+      window.removeEventListener("scroll", place, true);
+      document.removeEventListener("focusin", focus);
+    };
+  }, [error, showError]);
+  function commit() {
+    const number = Number(text);
+    if (!text.trim() || !Number.isFinite(number) || number < min || number > max) {
+      setError(`${label} must be ${min}–${max}${unit ? ` ${unit}` : ""}. Escape restores the previous value.`);
+      setShowError(true);
+    } else {
+      setError("");
+      if (number !== value) onCommit(number);
+    }
+    onEditEnd();
+  }
+  return <Field label={label}>
+    <span className={unit ? "parameter-input" : "number-input"}>
+      <input ref={input} name={name} type="number" autoComplete="off" min={min} max={max} step={step}
+        value={text} aria-invalid={error ? true : undefined} aria-describedby={error ? id : undefined}
+        onChange={event => setText(event.target.value)} onFocus={() => setShowError(true)} onBlur={commit}
+        onKeyDown={event => {
+          if ((event.metaKey || event.ctrlKey) && ["z", "y"].includes(event.key.toLowerCase()) && text !== String(value)) event.stopPropagation();
+          if (event.key === "Enter") { event.preventDefault(); commit(); }
+          if (event.key === "Escape") {
+            event.preventDefault(); event.stopPropagation();
+            setText(String(value)); setError(""); onEditEnd();
+          }
+        }} />
+      {unit && <span className="parameter-unit" aria-hidden="true">{unit}</span>}
+    </span>
+    {error && createPortal(<span id={id} role="alert" className={showError ? "parameter-error" : "sr-only"} style={showError ? position : undefined}>{error}</span>, document.body)}
+  </Field>;
+}
+
 export function Field({
   label,
   children,

package/src/lib/storage.ts

@@ -5,39 +5,67 @@ import {
   type Draft,
 } from "./model.ts";
 export const storageKey = "konpeki-composer/v1";
+export const exampleStorageKey = (name: string) =>
+  `konpeki-composer/examples/v1/${encodeURIComponent(name)}`;
 export type LoadedDraft = {
   draft: Draft;
   storageBlocked: boolean;
   error?: string;
 };
-export function loadDraft(): LoadedDraft {
+function loadStoredDraft(
+  key: string,
+  fallback: Draft,
+  unreadableMessage: string,
+): LoadedDraft {
   try {
-    const saved = localStorage.getItem(storageKey);
-    if (saved === null) return { draft: initialDraft(true), storageBlocked: false };
+    const saved = localStorage.getItem(key);
+    if (saved === null) return { draft: fallback, storageBlocked: false };
     const result = parseStoredDraft(saved);
     return result.ok
       ? { draft: result.draft, storageBlocked: false }
       : {
-          draft: initialDraft(true),
+          draft: fallback,
           storageBlocked: true,
-          error:
-            "Saved data could not be read. It has not been changed. Reset saved draft to recover.",
+          error: unreadableMessage,
         };
   } catch {
     return {
-      draft: initialDraft(true),
+      draft: fallback,
       storageBlocked: true,
       error:
-        "Storage is unavailable. You can still export your work; reset to retry saving.",
+        "Browser storage is unavailable. You can still download JSON; reset to retry saving.",
     };
   }
 }
-export function persistDraft(draft: Draft) {
+function persistStoredDraft(key: string, draft: Draft) {
   const value = serializeDraft(draft);
   if (!parseStoredDraft(value).ok)
     throw new Error("Invalid draft cannot be saved.");
-  localStorage.setItem(storageKey, value);
+  localStorage.setItem(key, value);
+}
+export function loadDraft(): LoadedDraft {
+  return loadStoredDraft(
+    storageKey,
+    initialDraft(true),
+    "Saved data could not be read. It has not been changed. Reset saved draft to recover.",
+  );
+}
+export function loadExampleDraft(name: string, bundled: Draft): LoadedDraft {
+  return loadStoredDraft(
+    exampleStorageKey(name),
+    bundled,
+    "This example's saved working copy could not be read. It has not been changed. Reset the example to recover.",
+  );
+}
+export function persistDraft(draft: Draft) {
+  persistStoredDraft(storageKey, draft);
+}
+export function persistExampleDraft(name: string, draft: Draft) {
+  persistStoredDraft(exampleStorageKey(name), draft);
 }
 export function clearStoredDraft() {
   localStorage.removeItem(storageKey);
 }
+export function clearStoredExampleDraft(name: string) {
+  localStorage.removeItem(exampleStorageKey(name));
+}

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

@@ -35,6 +35,8 @@ export function useFileSession(
   const reviewRef = useRef(review);
   const buildPending = useRef(false);
   const submittingBuild = useRef(false);
+  const loading = useRef(false);
+  const loadGeneration = useRef(0);
   const callbacksRef = useRef(callbacks);
   callbacksRef.current = callbacks;
   const draftRef = useRef(draft);
@@ -49,29 +51,15 @@ export function useFileSession(
 
   useEffect(() => {
     if (!enabled || !token) return;
-    let cancelled = false;
-    void loadFileSession(token).then((session) => {
-      if (cancelled) return;
-      state.current = {
-        ready: true,
-        revision: session.revision,
-        savedJSON: canonicalJSON(session.document),
-      };
-      setStatus("saved");
-      receiveReview(session.review);
-      callbacksRef.current.onOpen(session.document, session.name);
-    }).catch((error) => {
-      if (cancelled) return;
-      setStatus("error");
-      callbacksRef.current.onError(
-        error instanceof Error ? error.message : "Could not open the file-backed composition.",
-      );
-    });
-    return () => { cancelled = true; };
+    void reload();
+    return () => {
+      loadGeneration.current++;
+      loading.current = false;
+    };
   }, [enabled, token]);
 
   useEffect(() => {
-    if (!enabled || !state.current.ready || ["conflict", "error"].includes(status))
+    if (!enabled || !state.current.ready || ["loading", "conflict", "error"].includes(status))
       return;
     if (!validateComposition(draft).ok) return;
     const timer = window.setTimeout(() => { void save(draft); }, 250);
@@ -82,19 +70,20 @@ export function useFileSession(
     if (!enabled || !token) return;
     let cancelled = false;
     const timer = window.setInterval(() => {
-      if (!state.current.ready || state.current.drain || submittingBuild.current) return;
+      if (!state.current.ready || loading.current || state.current.drain || submittingBuild.current) return;
       const revision = state.current.revision;
+      const generation = loadGeneration.current;
       void loadFileSession(token).then((remote) => {
-        if (cancelled || state.current.drain || submittingBuild.current || revision !== state.current.revision) return;
+        if (cancelled || generation !== loadGeneration.current || loading.current || state.current.drain || submittingBuild.current || revision !== state.current.revision) return;
         receiveReview(remote.review);
-        setStatus(current => current === "error" ? "saved" : current);
+        if (canonicalJSON(draftRef.current) === state.current.savedJSON) {
+          setStatus("saved");
+          callbacksRef.current.onError("");
+        }
         if (remote.revision === revision) return;
         if (canonicalJSON(draftRef.current) !== state.current.savedJSON) {
           setStatus("conflict");
-          callbacksRef.current.onNotice(
-            "The file changed elsewhere. Neither version was overwritten.",
-            "error",
-          );
+          callbacksRef.current.onError("The file changed elsewhere. Your browser edits are not saved; neither version was overwritten.");
           return;
         }
         state.current = {
@@ -104,12 +93,10 @@ export function useFileSession(
         };
         setStatus("saved");
         callbacksRef.current.onExternalChange(remote.document);
-      }).catch(() => {
-        if (cancelled || submittingBuild.current || revision !== state.current.revision) return;
+      }).catch((error) => {
+        if (cancelled || generation !== loadGeneration.current || loading.current || state.current.drain || submittingBuild.current || revision !== state.current.revision) return;
         setStatus("error");
-        if (buildPending.current) {
-          callbacksRef.current.onNotice("Could not load the agent result. Check the local file service.", "error");
-        }
+        callbacksRef.current.onError(`Could not load the latest file. ${error instanceof Error ? error.message : "Check the local file service."}`);
       });
     }, 1000);
     return () => {
@@ -132,6 +119,7 @@ export function useFileSession(
   }
 
   async function noteAction(action: () => Promise<ReviewState>, saveFirst = false) {
+    if (loading.current || !state.current.ready) throw new Error("Wait for the file to open before submitting.");
     if (submittingBuild.current) throw new Error("Wait for the current save before submitting.");
     submittingBuild.current = true;
     try {
@@ -141,7 +129,8 @@ export function useFileSession(
   }
 
   function save(next: Draft): Promise<string | undefined> {
-    if (!token || !state.current.ready || activeRequest(reviewRef.current.request)) return Promise.resolve(undefined);
+    if (!token || loading.current || !state.current.ready || activeRequest(reviewRef.current.request)) return Promise.resolve(undefined);
+    if (!validateComposition(next).ok) return Promise.resolve(undefined);
     const serialized = canonicalJSON(next);
     if (serialized === state.current.savedJSON && !state.current.drain)
       return Promise.resolve(state.current.revision);
@@ -170,15 +159,15 @@ export function useFileSession(
         state.current.revision = result.revision;
         state.current.savedJSON = pending.serialized;
         setStatus("saved");
+        callbacksRef.current.onError("");
       } catch (error) {
         state.current.pending = undefined;
         const conflict = error instanceof FileSessionError && error.status === 409;
         setStatus(conflict ? "conflict" : "error");
-        callbacksRef.current.onNotice(
+        callbacksRef.current.onError(
           conflict
-            ? "The composition changed outside this browser. Your edits were not overwritten."
-            : error instanceof Error ? error.message : "Could not save the composition file.",
-          "error",
+            ? "The file changed elsewhere. Your browser edits are not saved; neither version was overwritten."
+            : `Changes are not saved. ${error instanceof Error ? error.message : "Could not save the composition file."}`,
         );
         return;
       }
@@ -191,7 +180,7 @@ export function useFileSession(
     componentId?: string,
     elementId?: string,
   ) {
-    if (!token || buildPending.current) return false;
+    if (!token || loading.current || !state.current.ready || buildPending.current) return false;
     if (submittingBuild.current) throw new Error("Wait for your note to finish saving before building.");
     buildPending.current = true;
     submittingBuild.current = true;
@@ -218,8 +207,41 @@ export function useFileSession(
     }
   }
 
+  async function reload() {
+    if (!token || loading.current || state.current.drain || submittingBuild.current) return;
+    loading.current = true;
+    const generation = ++loadGeneration.current;
+    const requestedJSON = canonicalJSON(draftRef.current);
+    setStatus("loading");
+    try {
+      const session = await loadFileSession(token);
+      if (generation !== loadGeneration.current) return;
+      if (canonicalJSON(draftRef.current) !== requestedJSON) {
+        setStatus("conflict");
+        callbacksRef.current.onError("Your browser edits changed while opening the file. Neither version was overwritten. Download JSON before loading the file again.");
+        return;
+      }
+      state.current = { ready: true, revision: session.revision, savedJSON: canonicalJSON(session.document) };
+      draftRef.current = session.document;
+      receiveReview(session.review);
+      callbacksRef.current.onOpen(session.document, session.name);
+      callbacksRef.current.onError("");
+      setStatus("saved");
+    } catch (error) {
+      if (generation !== loadGeneration.current) return;
+      setStatus("error");
+      callbacksRef.current.onError(error instanceof Error ? error.message : "Could not open the file.");
+    } finally {
+      if (generation === loadGeneration.current) loading.current = false;
+    }
+  }
+
   return {
     status, build, building, review,
+    opening: status === "loading",
+    ready: state.current.ready,
+    reload,
+    retry: () => state.current.ready && !activeRequest(reviewRef.current.request) ? save(draftRef.current) : reload(),
     addNote: (target: ReviewTarget, text: string) => noteAction(() => addNote(token!, target, text), true),
     removeNote: (id: string) => noteAction(() => removeNote(token!, id)),
     cancel: () => noteAction(() => cancelRequest(token!, reviewRef.current.request!.id)),

package/src/main.tsx

@@ -9,6 +9,9 @@ import "@fontsource/ibm-plex-serif/latin-600.css";
 import "@fontsource/noto-sans/latin-400.css";
 import "@fontsource/noto-sans/latin-500.css";
 import "@fontsource/noto-sans/latin-600.css";
+import "@fontsource/hanken-grotesk/latin-400.css";
+import "@fontsource/hanken-grotesk/latin-500.css";
+import "@fontsource/hanken-grotesk/latin-600.css";
 import { App } from "./app/App.tsx";
 import "./styles/base.css";
 import "./styles/shell.css";

package/src/styles/base.css

@@ -17,6 +17,7 @@
   --ui-hover: #f2f2f2;
   --ui-selected: #edf6fa;
   --ui-shadow: 0 8px 28px #00000014, 0 1px 3px #00000012;
+  --ui-floating-shadow: 0 0 0 1px #0000000f, 0 2px 4px #00000006, 0 8px 24px #0000000a;
 }
 * {
   box-sizing: border-box;
@@ -52,6 +53,12 @@ button:disabled {
   cursor: default;
   color: #767676;
 }
+.right-panel input[type="number"],
+.revision-note-count,
+.overflow-trigger,
+.thumbnail-page-number {
+  font-variant-numeric: tabular-nums;
+}
 :focus-visible {
   outline: 2px solid var(--accent);
   outline-offset: 3px;