@bookklik/pivo-plate 0.2.0 → 0.2.1

package/README.md

@@ -8,6 +8,10 @@ A local-first browser tile-to-3D modeling editor.
 
 ## npm and headless SDK
 
+For the full visual editor without its suite header or recovery startup, load `?embed=1`. Use `?recovery=off` to keep the header but disable browser recovery. Existing backups are preserved; see [browser embedding options](docs/npm.md#browser-embedding-and-recovery-options).
+
+Embed custom UIs or Node jobs with `createHeadlessEditor` from the root or `/headless` entry. It isolates documents and validates synchronous transactions; see [the embedding API](docs/npm.md#embed-with-a-custom-ui-or-no-ui).
+
 ESM library for Node.js 24+, with generated TypeScript declarations. After publication, install with `npm install @bookklik/pivo-plate` and import from `@bookklik/pivo-plate/headless`, `@bookklik/pivo-plate/core` or `@bookklik/pivo-plate/io`. No CLI or browser is required for the documented portable operations.
 
 See [SDK usage, supported operations and manual publishing](docs/npm.md). Build with `npm run build:lib`; validate an isolated production install with `npm run check:consumer`. These commands do not run the unit suite.

package/docs/npm.md

@@ -41,6 +41,48 @@ Calls do not open windows, start servers, contact remote services or access brow
 
 The SDK uses the existing bounded project/PNG/codec validators. Headless calls execute in the caller's thread: Promise-returning APIs do not imply background workers. For untrusted batches, isolate work in your own Node worker/process with memory/time budgets and terminate the worker for cancellation. There is no built-in Node worker/progress adapter. Model capture, browser PWA/recovery, and UI interactions remain editor features, not implicit headless capabilities.
 
+## Browser embedding and recovery options
+
+These URL options apply to the full browser editor and standalone HTML, not the UI-free SDK:
+
+| URL option | Header | Editor workspace | Browser recovery |
+| --- | --- | --- | --- |
+| No option | Visible | Mounted | Enabled |
+| `?recovery=off` | Visible | Mounted | Disabled |
+| `?embed=1` | Hidden | Mounted | Disabled |
+
+For example, load `/pivo-plate/?embed=1` directly or as an iframe's `src`. Keep the iframe sized to the space allocated by the host. If the URL already has a query string, append `&embed=1` instead. This is visual embedding, distinct from importing the headless SDK.
+
+Embedded mode hides only `.suite-header` and removes its layout space. Document/mode tabs, context toolbars, side panels, canvas, timeline where applicable, and status UI remain mounted. The hidden header is excluded from layout, accessibility navigation, and keyboard focus; its internal DOM is retained so existing editor command wiring stays intact. Native keyboard shortcuts, including Ctrl/Cmd+S for project downloads, continue to work. This option does not add a cross-origin postMessage/host-control bridge.
+
+`?recovery=off` disables discovery, legacy migration, recovery prompts, background autosaves, and recovery reads/writes/deletions for that page session. It does not erase existing backups. The status strip shows **Browser recovery disabled**. Remove the option and reload to resume normal recovery. `recovery=false` and `recovery=0` are aliases; `embed=true` and `embed=on` enable embedded mode. Embedded mode always disables recovery, even with `recovery=on` in the same URL.
+
+Unsaved-change warnings remain active. PWA updates are blocked while unsaved documents have no recovery copy; download all current projects before updating. Theme, workspace, tutorial preferences, and PWA asset caching are separate features and are not disabled by the recovery flag. This is not a private/incognito or storage-free browsing mode.
+
+The headless SDK already performs no browser recovery lookup or automatic persistence and needs neither URL option. To validate the browser modes after `npm run build`, use `npm run test:embed`; it exercises desktop and compact Chromium layouts, hidden-header spacing, native keyboard saving, and absence of recovery storage access. Set `PIVO_BROWSERS=chromium,firefox,webkit` to run the same checks in all three engines.
+
+## Embed with a custom UI or no UI
+
+The root and `/headless` entries export `createHeadlessEditor` and the `HeadlessEditor` TypeScript interface. Each instance owns an isolated project; it does not mount the editor, touch the DOM/storage, register service workers, start a server, or render a viewport. Use it in your host application's framework or a Node job, with the existing core operations and IO exporters.
+
+```js
+import { createHeadlessEditor, createProject } from '@bookklik/pivo-plate/headless';
+
+const editor = createHeadlessEditor(createProject());
+editor.transact(draft => {
+  draft.name = 'Embedded project';
+});
+const project = editor.getProject();
+```
+
+- `getProject()` returns a detached snapshot, including Craft pixel buffers. Mutating it does not edit the instance.
+- `transact(callback)` edits a private draft and validates before atomically adopting a detached copy. Throws, invalid documents, Promise/thenable callbacks, and reentrant mutations leave the previous project intact. Callbacks must be synchronous; await external work before opening a transaction. Late writes to a retained draft cannot change committed state.
+- `replace(project)` validates and detaches a replacement before adopting it. The seed and replacement remain caller-owned.
+
+Call your renderer or framework's state setter with `editor.getProject()` after a successful edit. Export that snapshot using this package's IO APIs. Persistence, rendering, subscriptions, undo/redo, and worker scheduling are explicit host responsibilities; the adapter does not silently persist changes or retain an undo history. Existing lower-level history/store APIs remain available separately. For React, create one instance per mounted editor rather than one on every render. For servers, create one instance per document/job, never a shared global editor for multiple tenants.
+
+The adapter is headless application logic, not an iframe bridge, a DOM editor widget, an HTTP API, or a CLI flag. Large validation/export calls still run in the calling thread. For untrusted input, use worker/process isolation and external memory/time limits in addition to the built-in format budgets. Embedded browser hosts must bundle the ESM package and its production dependencies; the browser UI and its PWA/recovery code are not needed.
+
 ## Build and artifact validation
 
 ```sh

package/lib/build.json

@@ -1,12 +1,13 @@
 {
   "name": "@bookklik/pivo-plate",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "inputs": [
     "src/core/png.ts",
     "src/core/types.ts",
     "src/core/hierarchy.ts",
     "src/core/editor.ts",
     "sdk/core.ts",
+    "sdk/editor.ts",
     "src/io/util.ts",
     "src/io/validate.ts",
     "src/io/container.ts",

package/lib/chunks/{chunk-OYM3ZMMA.js → chunk-PPDBMDTW.js}

@@ -1132,6 +1132,7 @@ var EditorStore = class {
 export {
   PNG_LIMITS,
   PROJECT_PNG_LIMITS,
+  pngCrc32,
   validatePngBytes,
   pngDataUrlBytes,
   pngBytesDataUrl,

package/lib/chunks/{chunk-DKWUGCIO.js → chunk-ZZLZL64O.js}

@@ -3,11 +3,12 @@ import {
   PROJECT_PNG_LIMITS,
   isObjectVisibleValue,
   pngBytesDataUrl,
+  pngCrc32,
   pngDataUrlBytes,
   validatePngBytes,
   validatePngDataUrl,
   validateProject
-} from "./chunk-OYM3ZMMA.js";
+} from "./chunk-PPDBMDTW.js";
 
 // src/io/util.ts
 import { zipSync, unzipSync, strFromU8, strToU8 } from "fflate";
@@ -96,6 +97,51 @@ function buildContainer(projectJson, textures) {
   if (bytes.length > LIMITS.maxCompressed) throw new ContainerError("Encoded project exceeds compressed archive budget");
   return bytes;
 }
+function inspectZip(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let end = -1;
+  for (let offset = bytes.length - 22; offset >= Math.max(0, bytes.length - 65557); offset--) {
+    if (view.getUint32(offset, true) === 101010256 && offset + 22 + view.getUint16(offset + 20, true) === bytes.length) {
+      end = offset;
+      break;
+    }
+  }
+  if (end < 0) throw new ContainerError("Missing ZIP directory");
+  const count = view.getUint16(end + 10, true);
+  const centralSize = view.getUint32(end + 12, true);
+  const centralOffset = view.getUint32(end + 16, true);
+  if (count > LIMITS.maxEntries) throw new ContainerError("Project archive contains too many files");
+  if (view.getUint16(end + 4, true) !== 0 || view.getUint16(end + 6, true) !== 0 || view.getUint16(end + 8, true) !== count || centralOffset + centralSize !== end) {
+    throw new ContainerError("Unsupported or inconsistent ZIP directory");
+  }
+  const directory = /* @__PURE__ */ new Map();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let position = centralOffset;
+  for (let index = 0; index < count; index++) {
+    if (position + 46 > end || view.getUint32(position, true) !== 33639248) throw new ContainerError("Invalid ZIP directory entry");
+    const flags = view.getUint16(position + 8, true);
+    const method = view.getUint16(position + 10, true);
+    const crc = view.getUint32(position + 16, true);
+    const packed = view.getUint32(position + 20, true);
+    const size = view.getUint32(position + 24, true);
+    const nameLength = view.getUint16(position + 28, true);
+    const next = position + 46 + nameLength + view.getUint16(position + 30, true) + view.getUint16(position + 32, true);
+    const local = view.getUint32(position + 42, true);
+    if (next > end || local + 30 > centralOffset || view.getUint16(position + 34, true) !== 0 || (flags & 1) !== 0 || method !== 0 && method !== 8) throw new ContainerError("Unsupported ZIP entry");
+    const name = decoder.decode(bytes.subarray(position + 46, position + 46 + nameLength));
+    if (!safeEntryPath(name)) throw new ContainerError(`Project archive contains a disallowed path "${name}" (expected project.json or atlases/<id>.png)`);
+    if (directory.has(name)) throw new ContainerError("Duplicate ZIP entry");
+    if (view.getUint32(local, true) !== 67324752 || view.getUint16(local + 6, true) !== flags || view.getUint16(local + 8, true) !== method) throw new ContainerError("Inconsistent ZIP local header");
+    const localNameLength = view.getUint16(local + 26, true);
+    const start = local + 30 + localNameLength + view.getUint16(local + 28, true);
+    if (start + packed > centralOffset || decoder.decode(bytes.subarray(local + 30, local + 30 + localNameLength)) !== name) throw new ContainerError("Inconsistent ZIP payload");
+    if ((flags & 8) === 0 && (view.getUint32(local + 14, true) !== crc || view.getUint32(local + 18, true) !== packed || view.getUint32(local + 22, true) !== size)) throw new ContainerError("Inconsistent ZIP entry sizes or checksum");
+    directory.set(name, { size, crc });
+    position = next;
+  }
+  if (position !== end) throw new ContainerError("ZIP directory count mismatch");
+  return directory;
+}
 function openContainer(bytes) {
   if (!(bytes instanceof Uint8Array) || bytes.length === 0) {
     throw new ContainerError("Project file is empty or unreadable");
@@ -106,7 +152,9 @@ function openContainer(bytes) {
   let raw;
   let declaredTotal = 0, entryCount = 0;
   const seen = /* @__PURE__ */ new Set();
+  let directory;
   try {
+    directory = inspectZip(bytes);
     raw = unzipSync(bytes, {
       filter: (file) => {
         if (++entryCount > LIMITS.maxEntries) throw new ContainerError("Project archive contains too many files");
@@ -127,6 +175,11 @@ function openContainer(bytes) {
     );
   }
   const names = Object.keys(raw);
+  if (names.length !== directory.size) throw new ContainerError("ZIP entry inventory mismatch");
+  for (const name of names) {
+    const expected = directory.get(name);
+    if (!expected || raw[name].length !== expected.size || pngCrc32(raw[name]) !== expected.crc) throw new ContainerError("ZIP entry size or checksum mismatch");
+  }
   if (names.length === 0) {
     throw new ContainerError("Project archive contains no files");
   }

package/lib/core.d.ts

@@ -1,5 +1,5 @@
-import { g as Project, h as Selection, B as Brush, A as Atlas, V as Vec2, E as EditorSession, i as Vec3, T as Tile, c as Plane } from './types/png-CEL_ylyR.js';
-export { a as AtlasRegion, D as DEFAULT_OBJECT_ID, M as Mode, P as PNG_LIMITS, b as PROJECT_PNG_LIMITS, d as PngAlphaMode, e as PngInfo, f as PngLimits, S as SceneObject, p as pngBytesDataUrl, j as pngDataUrlBytes, v as validatePngBytes, k as validatePngDataUrl } from './types/png-CEL_ylyR.js';
+import { P as Project, h as Selection, B as Brush, A as Atlas, V as Vec2, E as EditorSession, i as Vec3, T as Tile, d as Plane } from './types/png-XcN3Et0R.js';
+export { a as AtlasRegion, D as DEFAULT_OBJECT_ID, M as Mode, b as PNG_LIMITS, c as PROJECT_PNG_LIMITS, e as PngAlphaMode, f as PngInfo, g as PngLimits, S as SceneObject, p as pngBytesDataUrl, j as pngDataUrlBytes, v as validatePngBytes, k as validatePngDataUrl } from './types/png-XcN3Et0R.js';
 
 /** Hard cap on parent-chain depth for any object in a valid project. */
 declare const MAX_HIERARCHY_DEPTH = 128;

package/lib/core.js

@@ -35,7 +35,7 @@ import {
   validatePngBytes,
   validatePngDataUrl,
   validateProject
-} from "./chunks/chunk-OYM3ZMMA.js";
+} from "./chunks/chunk-PPDBMDTW.js";
 export {
   EditorStore,
   MAX_HIERARCHY_DEPTH,

package/lib/index.d.ts

@@ -1,3 +1,14 @@
 export { EditorStore, MAX_HIERARCHY_DEPTH, UV_TOLERANCE, applyBrush, brushUVs, checkUvInRange, clone, createProject, createSession, deleteSelection, duplicateSelection, isObjectLocked, isObjectVisible, makeTile, normalizeUv, planePoint, reparentObject, reverseSelection, rotateSelection, scaleSelection, selectedCorners, snap, tileCorners, transformUVs, translateSelection, uid, v3, validateBrushAgainstAtlas, validateProject } from './core.js';
-export { A as Atlas, a as AtlasRegion, B as Brush, D as DEFAULT_OBJECT_ID, E as EditorSession, M as Mode, P as PNG_LIMITS, b as PROJECT_PNG_LIMITS, c as Plane, d as PngAlphaMode, e as PngInfo, f as PngLimits, g as Project, S as SceneObject, h as Selection, T as Tile, V as Vec2, i as Vec3, p as pngBytesDataUrl, j as pngDataUrlBytes, v as validatePngBytes, k as validatePngDataUrl } from './types/png-CEL_ylyR.js';
+import { P as Project } from './types/png-XcN3Et0R.js';
+export { A as Atlas, a as AtlasRegion, B as Brush, D as DEFAULT_OBJECT_ID, E as EditorSession, M as Mode, b as PNG_LIMITS, c as PROJECT_PNG_LIMITS, d as Plane, e as PngAlphaMode, f as PngInfo, g as PngLimits, S as SceneObject, h as Selection, T as Tile, V as Vec2, i as Vec3, p as pngBytesDataUrl, j as pngDataUrlBytes, v as validatePngBytes, k as validatePngDataUrl } from './types/png-XcN3Et0R.js';
 export { ContainerError, ExportError, PayloadError, ProjectIOError, decodeProject, encodeProject, exportGLB, exportOBJ, inspectAlpha } from './io.js';
+
+interface HeadlessEditor {
+    getProject(): Project;
+    transact(mutate: (draft: Project) => void): void;
+    replace(project: Project): void;
+}
+declare function createHeadlessEditor(initialProject?: Project): HeadlessEditor;
+
+export { Project, createHeadlessEditor };
+export type { HeadlessEditor };

package/lib/index.js

@@ -9,7 +9,7 @@ import {
   exportGLB,
   exportOBJ,
   inspectAlpha
-} from "./chunks/chunk-DKWUGCIO.js";
+} from "./chunks/chunk-ZZLZL64O.js";
 import {
   EditorStore,
   MAX_HIERARCHY_DEPTH,
@@ -46,7 +46,44 @@ import {
   validatePngBytes,
   validatePngDataUrl,
   validateProject
-} from "./chunks/chunk-OYM3ZMMA.js";
+} from "./chunks/chunk-PPDBMDTW.js";
+
+// sdk/editor.ts
+function normalize(project) {
+  return validateProject(project);
+}
+function createHeadlessEditor(initialProject = createProject()) {
+  let current = normalize(initialProject);
+  let transacting = false;
+  function assertIdle() {
+    if (transacting) throw new Error("Headless editor mutations cannot be nested");
+  }
+  return {
+    getProject() {
+      return structuredClone(current);
+    },
+    transact(mutate) {
+      assertIdle();
+      transacting = true;
+      try {
+        const draft = structuredClone(current);
+        const result = mutate(draft);
+        if (result !== null && (typeof result === "object" || typeof result === "function") && typeof result.then === "function") {
+          void Promise.resolve(result).catch(() => {
+          });
+          throw new Error("Headless editor transactions must be synchronous");
+        }
+        current = normalize(draft);
+      } finally {
+        transacting = false;
+      }
+    },
+    replace(project) {
+      assertIdle();
+      current = normalize(project);
+    }
+  };
+}
 export {
   ContainerError,
   EditorStore,
@@ -61,6 +98,7 @@ export {
   brushUVs,
   checkUvInRange,
   clone,
+  createHeadlessEditor,
   createProject,
   createSession,
   decodeProject,

package/lib/io.js

@@ -8,8 +8,8 @@ import {
   exportGLB,
   exportOBJ,
   inspectAlpha
-} from "./chunks/chunk-DKWUGCIO.js";
-import "./chunks/chunk-OYM3ZMMA.js";
+} from "./chunks/chunk-ZZLZL64O.js";
+import "./chunks/chunk-PPDBMDTW.js";
 export {
   ContainerError,
   ExportError,

package/lib/types/{png-CEL_ylyR.d.ts → png-XcN3Et0R.d.ts}

@@ -118,5 +118,5 @@ declare function validatePngDataUrl(url: string, expected?: {
     height: number;
 }): PngInfo;
 
-export { DEFAULT_OBJECT_ID as D, PNG_LIMITS as P, PROJECT_PNG_LIMITS as b, pngDataUrlBytes as j, validatePngDataUrl as k, pngBytesDataUrl as p, validatePngBytes as v };
-export type { Atlas as A, Brush as B, EditorSession as E, Mode as M, SceneObject as S, Tile as T, Vec2 as V, AtlasRegion as a, Plane as c, PngAlphaMode as d, PngInfo as e, PngLimits as f, Project as g, Selection as h, Vec3 as i };
+export { DEFAULT_OBJECT_ID as D, PNG_LIMITS as b, PROJECT_PNG_LIMITS as c, pngDataUrlBytes as j, validatePngDataUrl as k, pngBytesDataUrl as p, validatePngBytes as v };
+export type { Atlas as A, Brush as B, EditorSession as E, Mode as M, Project as P, SceneObject as S, Tile as T, Vec2 as V, AtlasRegion as a, Plane as d, PngAlphaMode as e, PngInfo as f, PngLimits as g, Selection as h, Vec3 as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookklik/pivo-plate",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "author": "a-hakim",
   "private": false,
@@ -13,6 +13,7 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:browser": "node scripts/browser-readiness.mjs",
+    "test:embed": "node scripts/browser-embed.mjs",
     "test:layout": "node tests/layout-check.mjs",
     "test:safety": "node tests/browser-safety.mjs",
     "test:modeling": "node tests/browser-modeling.mjs",
@@ -122,6 +123,8 @@
     "editor"
   ],
   "overrides": {
+    "glob": "14.0.3",
+    "minimatch": "11.0.1",
     "fast-uri": "3.1.9",
     "serialize-javascript": "7.1.3",
     "vitepress": {