konpeki 0.1.1 → 0.2.0

package/composition/validate.ts

@@ -1,9 +1,6 @@
 import { Ajv2020 } from "ajv/dist/2020.js";
 import { schema } from "./schema.ts";
-import { migrateLegacyDiagramType } from "./visualizations.ts";
 import {
-  compositionSchema,
-  legacyCompositionSchemas,
   type CompositionDocument,
 } from "./types.ts";
 import { vectorAttributeNames } from "./vector.ts";
@@ -17,461 +14,8 @@ const structural = new Ajv2020({
   allErrors: true,
   strict: false,
 }).compile<CompositionDocument>(schema);
-function migratePreV5Document(input: Record<string, unknown>) {
-  const slide = input.slide as Record<string, unknown> | undefined;
-  const components = Array.isArray(slide?.components)
-    ? slide.components.map((value: unknown) => {
-        if (!value || typeof value !== "object") return value;
-        const component = value as Record<string, unknown>;
-        if (
-          component.kind !== "callout" &&
-          component.kind !== "comparison" &&
-          component.kind !== "text-block"
-        )
-          return component;
-        const previous =
-          component.appearance && typeof component.appearance === "object"
-            ? (component.appearance as Record<string, unknown>)
-            : {};
-        const common = Object.fromEntries(
-          ["alignment", "border", "titleStyle", "rule"].flatMap((key) =>
-            key in previous ? [[key, previous[key]]] : [],
-          ),
-        );
-        const appearance =
-          component.kind === "callout"
-            ? {
-                ...common,
-                layout: "single",
-                orientation: "horizontal",
-                purpose: "emphasis",
-                treatment: "strong",
-              }
-            : component.kind === "comparison"
-              ? {
-                  ...common,
-                  layout: "two-column",
-                  orientation: "horizontal",
-                  purpose: "comparison",
-                  treatment: "plain",
-                }
-              : {
-                  ...previous,
-                  purpose: previous.purpose ?? "narrative",
-                  treatment: previous.treatment ?? "plain",
-                };
-        return { ...component, kind: "text-block", appearance };
-      })
-    : slide?.components;
-  return {
-    ...Object.fromEntries(
-      Object.entries(input).filter(
-        ([key]) => key !== "target" && key !== "slide",
-      ),
-    ),
-    schema: "konpeki-composition/v5",
-    ...(slide
-      ? { slides: [{ ...slide, name: "Slide 01", components }] }
-      : {}),
-  };
-}
-function migrateV5Document(input: Record<string, unknown>) {
-  const slides = Array.isArray(input.slides)
-    ? input.slides.map((value: unknown) => {
-        if (!value || typeof value !== "object") return value;
-        const slide = value as Record<string, unknown>;
-        const previousComponents = Array.isArray(slide.components)
-          ? (slide.components as Record<string, unknown>[])
-          : [];
-        const pageNumber = previousComponents.find(
-          (component) => component.kind === "page-number",
-        );
-        const pageAppearance =
-          pageNumber?.appearance && typeof pageNumber.appearance === "object"
-            ? (pageNumber.appearance as Record<string, unknown>)
-            : {};
-        const removedIds = new Set(
-          previousComponents
-            .filter((component) => component.kind === "page-number")
-            .map((component) => String(component.id)),
-        );
-        const removedSlots = new Set(
-          previousComponents
-            .filter((component) => component.kind === "page-number")
-            .flatMap((component) =>
-              Array.isArray(component.slotIds)
-                ? component.slotIds.map(String)
-                : [],
-            ),
-        );
-        const components = previousComponents.flatMap((component) => {
-          const appearance =
-            component.appearance && typeof component.appearance === "object"
-              ? (component.appearance as Record<string, unknown>)
-              : {};
-          if (component.kind === "page-number") return [];
-          if (component.kind === "evidence")
-            return [{ ...component, kind: "visual" }];
-          if (component.kind === "process")
-            return [
-              {
-                ...component,
-                kind: "diagram",
-                appearance: { ...appearance, type: "process" },
-              },
-            ];
-          if (component.kind === "system-map")
-            return [
-              {
-                ...component,
-                kind: "diagram",
-                appearance: { ...appearance, type: "system" },
-              },
-            ];
-          return [component];
-        });
-        const componentIds = new Set(components.map((component) => String(component.id)));
-        const groups = Array.isArray(slide.groups)
-          ? (slide.groups as Record<string, unknown>[])
-              .map((group) => ({
-                ...group,
-                childIds: Array.isArray(group.childIds)
-                  ? group.childIds.filter((id) => !removedIds.has(String(id)))
-                  : group.childIds,
-              }))
-              .filter(
-                (group) =>
-                  !Array.isArray(group.childIds) || group.childIds.length > 0,
-              )
-          : slide.groups;
-        const groupIds = new Set(
-          Array.isArray(groups)
-            ? groups.map((group) => String(group.id))
-            : [],
-        );
-        const contentSlots = Array.isArray(slide.contentSlots)
-          ? (slide.contentSlots as Record<string, unknown>[])
-              .filter((slot) => !removedSlots.has(String(slot.id)))
-              .map((slot) => {
-                if (!Array.isArray(slot.targets)) return slot;
-                const targets = slot.targets.filter(
-                  (target) =>
-                    !removedIds.has(String(target)) &&
-                    !removedSlots.has(String(target)),
-                );
-                return {
-                  ...slot,
-                  targets: targets.length
-                    ? targets
-                    : [String(components[0]?.id ?? "")],
-                };
-              })
-          : slide.contentSlots;
-        return {
-          ...slide,
-          pageNumber: {
-            style: pageNumber ? (pageAppearance.style ?? "01") : "none",
-            color: pageAppearance.color ?? "muted",
-          },
-          components,
-          contentSlots,
-          groups,
-          readingOrder: Array.isArray(slide.readingOrder)
-            ? (slide.readingOrder as Record<string, unknown>[]).filter((entry) =>
-                entry.kind === "group"
-                  ? groupIds.has(String(entry.id))
-                  : componentIds.has(String(entry.id)),
-              )
-            : slide.readingOrder,
-          paintOrder: Array.isArray(slide.paintOrder)
-            ? slide.paintOrder.filter((id) => !removedIds.has(String(id)))
-            : slide.paintOrder,
-          relationships: Array.isArray(slide.relationships)
-            ? (slide.relationships as Record<string, unknown>[]).filter(
-                (relationship) => {
-                  const from = relationship.from as Record<string, unknown> | undefined;
-                  const to = relationship.to as Record<string, unknown> | undefined;
-                  return (
-                    !removedIds.has(String(from?.nodeId)) &&
-                    !removedIds.has(String(to?.nodeId))
-                  );
-                },
-              )
-            : slide.relationships,
-        };
-      })
-    : input.slides;
-  return { ...input, schema: compositionSchema, slides };
-}
-function migrateV7Document(input: Record<string, unknown>) {
-  const slides = Array.isArray(input.slides)
-    ? input.slides.map((value: unknown) => {
-        if (!value || typeof value !== "object") return value;
-        const slide = value as Record<string, unknown>;
-        const components = Array.isArray(slide.components)
-          ? slide.components.map((value: unknown) => {
-              if (!value || typeof value !== "object") return value;
-              const component = value as Record<string, unknown>;
-              const appearance =
-                component.appearance && typeof component.appearance === "object"
-                  ? (component.appearance as Record<string, unknown>)
-                  : {};
-              if (component.kind !== "visual" || appearance.template !== "image")
-                return component;
-              return {
-                ...component,
-                kind: "image",
-                appearance: {
-                  ...(appearance.border ? { border: appearance.border } : {}),
-                  fit: "contain",
-                },
-              };
-            })
-          : slide.components;
-        return { ...slide, components };
-      })
-    : input.slides;
-  return { ...input, schema: compositionSchema, slides };
-}
-function migrateV10Document(input: Record<string, unknown>) {
-  const slides = Array.isArray(input.slides)
-    ? input.slides.map((value: unknown) => {
-        if (!value || typeof value !== "object") return value;
-        const slide = value as Record<string, unknown>;
-        const components = Array.isArray(slide.components)
-          ? slide.components.map((value: unknown) => {
-              if (!value || typeof value !== "object") return value;
-              const component = value as Record<string, unknown>;
-              const appearance =
-                component.appearance && typeof component.appearance === "object"
-                  ? (component.appearance as Record<string, unknown>)
-                  : {};
-              if (component.kind === "headline")
-                return {
-                  ...component,
-                  kind: "text-block",
-                  appearance: {
-                    ...appearance,
-                    role: "title",
-                    layout: "single",
-                    orientation: "horizontal",
-                    purpose: "narrative",
-                    treatment: "plain",
-                    logicalOrder: "none",
-                  },
-                };
-              if (component.kind === "footnote")
-                return {
-                  ...component,
-                  kind: "text-block",
-                  appearance: {
-                    ...appearance,
-                    role: "footnote",
-                    layout: "single",
-                    orientation: "horizontal",
-                    purpose: "narrative",
-                    treatment: "plain",
-                    logicalOrder: "none",
-                    titleStyle: "plain",
-                  },
-                };
-              if (component.kind === "text-block")
-                return {
-                  ...component,
-                  appearance: { role: "body", ...appearance },
-                };
-              if (component.kind === "visual")
-                return { ...component, kind: "chart" };
-              if (component.kind === "diagram") {
-                const { template, ...rest } = appearance;
-                return {
-                  ...component,
-                  appearance: {
-                    ...rest,
-                    layout: template ?? appearance.layout ?? "linear",
-                  },
-                };
-              }
-              if (component.kind === "icon" || component.kind === "shape") {
-                const slotIds = Array.isArray(component.slotIds)
-                  ? component.slotIds.map(String)
-                  : [];
-                const slotId = slotIds[0] ?? `${String(component.id)}-content`;
-                const primitive = component.kind === "icon"
-                  ? {
-                      kind: "icon" as const,
-                      ...(typeof component.intent === "string" && component.intent.trim()
-                        ? { name: component.intent.trim() }
-                        : {}),
-                      ...(appearance.style ? { style: appearance.style } : {}),
-                      ...(appearance.color ? { color: appearance.color } : {}),
-                    }
-                  : {
-                      kind: "shape" as const,
-                      shape: appearance.shape ?? "rectangle",
-                      ...(appearance.color ? { color: appearance.color } : {}),
-                      ...(appearance.fill ? { fill: appearance.fill } : {}),
-                    };
-                return {
-                  ...component,
-                  kind: "diagram",
-                  slotIds: slotIds.length ? slotIds : [slotId],
-                  appearance: {
-                    type: "system",
-                    layout: "hub-and-spoke",
-                    border: appearance.border ?? "none",
-                    colorScheme: "accent-with-muted-context",
-                    emphasis: "primary",
-                    density: "sparse",
-                  },
-                  topology: {
-                    kind: "explicit",
-                    nodes: (slotIds.length ? slotIds : [slotId]).map(
-                      (currentSlotId, index) => ({
-                        id: index
-                          ? `${String(component.id)}-slot-${index + 1}`
-                          : String(component.id),
-                        slotId: currentSlotId,
-                        ...(index ? { visible: false } : { primitive }),
-                        ...(component.preferredRect && typeof component.preferredRect === "object"
-                          ? { preferredRect: component.preferredRect }
-                          : {}),
-                      }),
-                    ),
-                    edges: [],
-                  },
-                };
-              }
-              return component;
-            })
-          : slide.components;
-        const contentSlots = Array.isArray(slide.contentSlots)
-          ? slide.contentSlots.map((value: unknown) => {
-              if (!value || typeof value !== "object") return value;
-              const slot = value as Record<string, unknown>;
-              return slot.role === "icon" || slot.role === "shape"
-                ? { ...slot, role: "entity" }
-                : slot;
-            })
-          : slide.contentSlots;
-        return { ...slide, components, contentSlots };
-      })
-    : input.slides;
-  return { ...input, schema: "konpeki-composition/v11", slides };
-}
-function migrateV11Document(input: Record<string, unknown>) {
-  const slides = Array.isArray(input.slides)
-    ? input.slides.map((value: unknown) => {
-        if (!value || typeof value !== "object") return value;
-        const slide = value as Record<string, unknown>;
-        const components = Array.isArray(slide.components)
-          ? slide.components.map((value: unknown) => {
-              if (!value || typeof value !== "object") return value;
-              const component = value as Record<string, unknown>;
-              if (component.kind !== "diagram") return component;
-              const appearance =
-                component.appearance && typeof component.appearance === "object"
-                  ? (component.appearance as Record<string, unknown>)
-                  : {};
-              const migratedType = migrateLegacyDiagramType(
-                appearance.type,
-                appearance.layout,
-              );
-              const { layout, ...rest } = appearance;
-              return {
-                ...component,
-                appearance: {
-                  ...rest,
-                  type: migratedType ?? null,
-                },
-              };
-            })
-          : slide.components;
-        return { ...slide, components };
-      })
-    : input.slides;
-  return { ...input, schema: compositionSchema, slides };
-}
-function migrateInterimV12Sankey(input: unknown) {
-  if (!input || typeof input !== "object") return input;
-  const document = input as Record<string, unknown>;
-  if (document.schema !== compositionSchema || !Array.isArray(document.slides))
-    return input;
-  const slides = document.slides.map((value: unknown) => {
-    if (!value || typeof value !== "object") return value;
-    const slide = value as Record<string, unknown>;
-    if (!Array.isArray(slide.components)) return value;
-    const components = slide.components.map((componentValue: unknown) => {
-      if (!componentValue || typeof componentValue !== "object") return componentValue;
-      const component = componentValue as Record<string, unknown>;
-      const appearance = component.appearance && typeof component.appearance === "object"
-        ? component.appearance as Record<string, unknown>
-        : {};
-      if (component.kind !== "diagram" || appearance.type !== "sankey")
-        return componentValue;
-      const { type: _type, ...sharedAppearance } = appearance;
-      return {
-        ...component,
-        kind: "chart",
-        appearance: { ...sharedAppearance, template: "sankey" },
-      };
-    });
-    return { ...slide, components };
-  });
-  return { ...document, slides };
-}
-function preserveLegacyVisualizationChoices(input: unknown) {
-  if (!input || typeof input !== "object") return input;
-  const document = input as Record<string, unknown>;
-  if (!Array.isArray(document.slides)) return input;
-  return { ...document, slides: document.slides.map((value: unknown) => {
-    if (!value || typeof value !== "object") return value;
-    const slide = value as Record<string, unknown>;
-    if (!Array.isArray(slide.components)) return value;
-    return { ...slide, components: slide.components.map((value: unknown) => {
-      if (!value || typeof value !== "object") return value;
-      const component = value as Record<string, unknown>;
-      if ((component.kind !== "diagram" && component.kind !== "chart") || !component.appearance || typeof component.appearance !== "object") return value;
-      return { ...component, appearance: { ...component.appearance, selection: "explicit" } };
-    }) };
-  }) };
-}
 export function validateComposition(input: unknown): ValidationResult {
-  const legacy = Boolean(
-    input &&
-      typeof input === "object" &&
-      "schema" in input &&
-      legacyCompositionSchemas.includes(
-        input.schema as (typeof legacyCompositionSchemas)[number],
-      ),
-  );
-  const legacyInput = input as Record<string, unknown>;
-  const migrated = legacy
-    ? ["konpeki-composition/v12", "konpeki-composition/v13", "konpeki-composition/v14", "konpeki-composition/v15", "konpeki-composition/v16", "konpeki-composition/v17"].includes(
-        String(legacyInput.schema),
-      )
-      ? { ...legacyInput, schema: compositionSchema }
-      : migrateV11Document(
-        legacyInput.schema === "konpeki-composition/v11"
-          ? legacyInput
-          : migrateV10Document(
-              ["konpeki-composition/v6", "konpeki-composition/v7", "konpeki-composition/v8", "konpeki-composition/v9", "konpeki-composition/v10"].includes(
-                String(legacyInput.schema),
-              )
-                ? migrateV7Document(legacyInput)
-                : migrateV7Document(
-                    migrateV5Document(
-                      legacyInput.schema === "konpeki-composition/v5"
-                        ? legacyInput
-                        : migratePreV5Document(legacyInput),
-                    ),
-                  ),
-            ),
-      )
-    : input;
-  const normalized = migrateInterimV12Sankey(migrated);
-  const candidate = legacy ? preserveLegacyVisualizationChoices(normalized) : normalized;
-  if (!structural(candidate))
+  if (!structural(input))
     return {
       ok: false,
       issues: (structural.errors ?? []).map((error) => ({
@@ -479,6 +23,7 @@ export function validateComposition(input: unknown): ValidationResult {
         message: error.message ?? "Invalid value",
       })),
     };
+  const candidate = input;
   const issues: ValidationIssue[] = [];
   const fail = (path: string, message: string) =>
     issues.push({ path, message });
@@ -667,10 +212,7 @@ export function validateComposition(input: unknown): ValidationResult {
   });
   return issues.length
     ? { ok: false, issues }
-    : { ok: true, document: legacy ? { ...candidate, slides: candidate.slides.map((slide) => ({
-        ...slide, components: slide.components.map((component) => component.kind === "text-block" && !component.customVisual && component.content === undefined
-          ? { ...component, content: component.intent ?? "" } : component),
-      })) } : candidate };
+    : { ok: true, document: input };
 }
 export function assertComposition(input: unknown): CompositionDocument {
   const result = validateComposition(input);

package/composition/visualizations.ts

@@ -317,19 +317,3 @@ export const diagramCategories = Array.from(
 export function diagramDefinition(type: DiagramType): DiagramDefinition {
   return diagramDefinitions[type];
 }
-
-export function migrateLegacyDiagramType(
-  type: unknown,
-  layout: unknown,
-): DiagramType | undefined {
-  if (typeof type !== "string" || typeof layout !== "string") return undefined;
-  const legacyTypes: Record<string, DiagramType> = {
-    "process/linear": "process",
-    "process/branching": "flowchart",
-    "process/cyclical": "loop-flywheel",
-    "system/layered": "layer-stack",
-    "system/request-flow": "sequence",
-    "system/hub-and-spoke": "architecture",
-  };
-  return legacyTypes[`${type}/${layout}`];
-}

package/docs/development.md

@@ -170,6 +170,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

@@ -49,13 +49,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "konpeki",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A shared editable canvas for agent-made visuals",
   "license": "Apache-2.0",
   "repository": {
@@ -72,12 +72,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"