@penpair/web 0.1.3 → 0.3.0

package/examples/theme-preview/readback.js

@@ -0,0 +1,7 @@
+// penpair: read
+const input = previewInput();
+const fill = input.root.fills && input.root.fills[0];
+return {ok:true,rootId:input.root.id,verification:{
+ expected:{color:input.value,opacity:1,fillBinding:null,provenance:input.provenance},
+ actual:{color:fill && fill.fillColor,opacity:fill && fill.fillOpacity,fillBinding:input.root.tokens.fill || null,provenance:input.root.getSharedPluginData("penpair","projection")}
+}};

package/examples/trials/hold-inspect.js

@@ -0,0 +1,5 @@
+// penpair: read
+if (penpot.currentFile.id !== CFG.fileId || penpot.currentPage.id !== CFG.pageId) throw new Error("Confirm the owner-authorized scratch file/page IDs");
+if (penpot.currentPage.root.children.length !== 0) throw new Error("Use the dedicated empty scratch page for the writer exercise");
+if (typeof CFG.marker !== "string" || !CFG.marker) throw new Error("A fresh trial marker is required");
+return { ok: true, fileId: penpot.currentFile.id, pageId: penpot.currentPage.id, children: 0 };

package/examples/trials/hold-readback.js

@@ -0,0 +1,8 @@
+// penpair: read
+const raw = penpot.currentFile.getSharedPluginData("penpair", "trial-hold-" + CFG.marker);
+let record = null;
+try { record = raw ? JSON.parse(raw) : null; } catch {}
+return { ok: true, verification: {
+  expected: { fileId: CFG.fileId, pageId: CFG.pageId, children: 0, marker: CFG.marker, holdMs: Number(CFG.holdMs), state: "complete" },
+  actual: { fileId: penpot.currentFile.id, pageId: penpot.currentPage.id, children: penpot.currentPage.root.children.length, marker: record?.marker ?? null, holdMs: record?.holdMs ?? null, state: record?.state ?? null }
+} };

package/examples/trials/hold-writer.js

@@ -0,0 +1,16 @@
+// penpair: write
+// penpair: idempotent
+const milliseconds = Number(CFG.holdMs);
+if (!Number.isInteger(milliseconds) || milliseconds < 1 || milliseconds > 30000) throw new Error("holdMs must be 1–30000");
+if (!CFG.inspection || penpot.currentFile.id !== CFG.inspection.fileId || penpot.currentPage.id !== CFG.inspection.pageId || penpot.currentPage.root.children.length !== 0) throw new Error("Scratch source changed before the hold");
+if (!CFG.marker) throw new Error("A fresh trial marker is required");
+const key = "trial-hold-" + CFG.marker;
+const prior = penpot.currentFile.getSharedPluginData("penpair", key);
+if (prior) throw new Error("Trial marker already exists; inspect it before recovery");
+const record = { schemaVersion: 1, state: "holding", marker: CFG.marker, fileId: CFG.fileId, pageId: CFG.pageId, holdMs: milliseconds };
+penpot.currentFile.setSharedPluginData("penpair", key, JSON.stringify(record));
+// This deliberate delay opens a controlled contention window. It is not layout settling.
+// The operation runner owns the advisory writer lease; this body changes no design objects.
+await new Promise(resolve => setTimeout(resolve, milliseconds));
+penpot.currentFile.setSharedPluginData("penpair", key, JSON.stringify({ ...record, state: "complete" }));
+return { ok: true, heldMilliseconds: milliseconds };

package/examples/trials/recovery-build.js

@@ -0,0 +1,23 @@
+// penpair: write
+// penpair: idempotent
+if (!CFG.inspection || penpot.currentFile.id !== CFG.fileId || penpot.currentPage.id !== CFG.pageId) throw new Error("Scratch identity changed");
+if (JSON.stringify(penpot.currentPage.root.children.map(shape => shape.id).sort()) !== JSON.stringify(CFG.inspection.rootIds)) throw new Error("Scratch source changed before the recovery exercise");
+if (CFG.inspection.existingId) {
+  const frame = penpot.currentPage.getShapeById(CFG.inspection.existingId);
+  if (!frame || frame.name !== CFG.name || frame.width !== 160 || frame.height !== 80 || frame.getSharedPluginData("penpair", "trial") !== CFG.marker) throw new Error("Owned frame has an unexplained third state");
+  return { ok: true, alreadyBuilt: true, frameId: frame.id };
+}
+let frame = null, configured = false;
+try {
+  frame = penpot.createBoard();
+  frame.name = CFG.name;
+  frame.setSharedPluginData("penpair", "trial", CFG.marker);
+  frame.fills = [];
+  frame.resize(160, 80);
+  configured = true;
+} finally {
+  if (!configured && frame) frame.remove();
+}
+// Deliberate fault: the owned write exists, but the normal acknowledgment is not returned.
+if (CFG.failAfterWrite === "true") throw new Error("Controlled trial failure after the owned write; inspect before explicit resume");
+return { ok: true, frameId: frame.id };

package/examples/trials/recovery-inspect.js

@@ -0,0 +1,10 @@
+// penpair: read
+if (penpot.currentFile.id !== CFG.fileId || penpot.currentPage.id !== CFG.pageId) throw new Error("Confirm the authorized scratch file/page IDs");
+if (typeof CFG.name !== "string" || !CFG.name || typeof CFG.marker !== "string" || !CFG.marker) throw new Error("A unique trial name and ownership marker are required");
+const matches = penpot.currentPage.root.children.filter(shape => shape.name === CFG.name);
+if (matches.length > 1) throw new Error("Recovery trial name is ambiguous");
+const frame = matches[0];
+const marked = penpot.currentPage.root.children.filter(shape => typeof shape.getSharedPluginData === "function" && shape.getSharedPluginData("penpair", "trial") === CFG.marker);
+if (marked.length > 1 || (marked.length === 1 && marked[0] !== frame)) throw new Error("Trial ownership marker moved or duplicated; inspect before recovery");
+if (frame && (typeof frame.getSharedPluginData !== "function" || frame.getSharedPluginData("penpair", "trial") !== CFG.marker)) throw new Error("Existing frame is not this trial's owned object");
+return { ok: true, existingId: frame?.id ?? null, width: frame?.width ?? null, height: frame?.height ?? null, rootIds: penpot.currentPage.root.children.map(shape => shape.id).sort() };

package/examples/trials/recovery-readback.js

@@ -0,0 +1,7 @@
+// penpair: read
+const matches = penpot.currentPage.root.children.filter(shape => shape.name === CFG.name);
+const frame = matches.length === 1 ? matches[0] : null;
+return { ok: true, frameId: frame?.id ?? null, verification: {
+  expected: { fileId: CFG.fileId, pageId: CFG.pageId, name: CFG.name, marker: CFG.marker, width: 160, height: 80 },
+  actual: frame ? { fileId: penpot.currentFile.id, pageId: penpot.currentPage.id, name: frame.name, marker: typeof frame.getSharedPluginData === "function" ? frame.getSharedPluginData("penpair", "trial") : null, width: frame.width, height: frame.height } : { missingOrAmbiguous: true }
+} };

package/examples/trials/wrong-file-read.js

@@ -0,0 +1,3 @@
+// penpair: read
+// A benign read: the configured same-execution file guard must block this body on the other file.
+return { ok: true, actualFileId: penpot.currentFile.id, actualPageId: penpot.currentPage.id };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/web",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "The penpair command for Penpot on the web (design.penpot.app or your team's own): guided setup, a safe write protocol, skills for AI agents. Includes everything in @penpair/core.",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,7 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "LICENSE",
     "README.md"
   ],
@@ -47,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@penpair/core": "0.1.3"
+    "@penpair/core": "0.3.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",