@bookklik/pivo-craft 0.6.0 → 0.6.1

package/README.md

@@ -8,6 +8,10 @@ A local-first browser pixel-art and animation 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-craft` and import from `@bookklik/pivo-craft/headless`, `@bookklik/pivo-craft/core` or `@bookklik/pivo-craft/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

@@ -42,6 +42,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-craft/?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-craft/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
@@ -67,7 +109,7 @@ npm publish --dry-run --access public
 npm publish --access public
 ```
 
-Only run the final command when you intend to publish. No workflow publishes automatically. Confirm npm login, package-name ownership and version availability first; registry E404 does not guarantee ownership. Before later releases, choose an unused semver version. prepublishOnly rejects any current npm audit vulnerability; prepack builds/checks the artifact and never runs unit tests. If publishing a previously created tarball rather than the project directory, run the release checks before packing: npm cannot rebuild a tarball for you. Configure provenance/trusted publishing according to your npm account if desired; no credentials are stored here.
+Only run the final command when you intend to publish. No workflow publishes automatically. Confirm npm login, package-name ownership and version availability first; registry E404 does not guarantee ownership. Before later releases, choose an unused semver version. prepublishOnly rejects npm audit vulnerabilities except the narrowly scoped, expiring deepmerge exception documented in the [dependency policy](production-readiness.md#dependency-policy-updated-28-october-2026); prepack builds/checks the artifact and never runs unit tests. If publishing a previously created tarball rather than the project directory, run the release checks before packing: npm cannot rebuild a tarball for you. Configure provenance/trusted publishing according to your npm account if desired; no credentials are stored here.
 
 The npm archive intentionally includes lib/, this document, README, LICENSE and the relevant third-party notices. Source, tests, tooling, app dist/ and standalone HTML are excluded. The root package has no dependency on another PiVo package: each can be published independently.
 

package/lib/build.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookklik/pivo-craft",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "inputs": [
     "packages/core/src/util.ts",
     "packages/core/src/color.ts",
@@ -15,8 +15,9 @@
     "packages/core/src/color-adjustments.ts",
     "packages/core/src/index.ts",
     "sdk/core.ts",
-    "packages/codecs/src/bytes.ts",
     "packages/codecs/src/project.ts",
+    "sdk/editor.ts",
+    "packages/codecs/src/bytes.ts",
     "packages/codecs/src/native.ts",
     "packages/codecs/src/zlib.ts",
     "packages/codecs/src/ase.ts",

package/lib/chunks/{chunk-DBS4XKWD.js → chunk-DVGCTRCE.js}

@@ -489,6 +489,8 @@ var IMAGES_PREFIX = "images/";
 var MAX_UNCOMPRESSED = 256 * 1024 * 1024;
 var MAX_MEMBERS = 32768;
 function saveNative(p) {
+  p = validateProjectShape(structuredClone(p));
+  validateProject(p);
   const imageRefs = [];
   const images = {};
   for (const [id, img] of Object.entries(p.images)) {
@@ -507,7 +509,13 @@ function saveNative(p) {
     [JSON_MEMBER]: new TextEncoder().encode(JSON.stringify(envelope)),
     ...images
   };
-  return zipSync(members, { level: 6 });
+  const entries = Object.values(members);
+  if (entries.length > MAX_MEMBERS || members[JSON_MEMBER].length > 16 * 1024 * 1024 || entries.reduce((total, data) => total + data.length, 0) > MAX_UNCOMPRESSED) {
+    throw new Error("Project exceeds native archive budgets");
+  }
+  const bytes = zipSync(members, { level: 6 });
+  if (bytes.length > 128 * 1024 * 1024) throw new Error("Encoded ZIP exceeds 128MiB");
+  return bytes;
 }
 function preflightZip(bytes) {
   if (bytes.length < 22) throw new Error("file too small for ZIP");
@@ -547,6 +555,7 @@ function preflightZip(bytes) {
   return directory;
 }
 function loadNative(bytes) {
+  if (!(bytes instanceof Uint8Array)) throw new Error("Native project must be a Uint8Array");
   const directory = preflightZip(bytes);
   let files;
   try {
@@ -584,10 +593,11 @@ function loadNative(bytes) {
   if (typeof projectRaw !== "object" || projectRaw === null) throw new Error("pvc envelope missing project");
   const images = {};
   for (const ref of env.imageRefs) {
+    if (!ref || typeof ref !== "object" || Array.isArray(ref)) throw new Error("bad imageRef");
     const id = typeof ref.id === "string" ? ref.id : "";
-    if (!id || id === "__proto__") throw new Error("bad imageRef id");
+    if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(id) || ["__proto__", "constructor", "prototype"].includes(id) || Object.hasOwn(images, id)) throw new Error("bad or duplicate imageRef id");
     const member = typeof ref.member === "string" ? ref.member : "";
-    const data = files[member];
+    const data = Object.hasOwn(files, member) && member.startsWith(IMAGES_PREFIX) ? files[member] : void 0;
     if (!data) throw new Error(`missing image member ${member}`);
     images[id] = {
       id,
@@ -600,15 +610,24 @@ function loadNative(bytes) {
   const tileSetRefs = Array.isArray(env.tileSetRefs) ? env.tileSetRefs : [];
   if (tileSetRefs.length > 1024) throw new Error("Too many tilesets");
   const tilesets = tileSetRefs.map((raw) => {
-    if (!Array.isArray(raw.tiles) || raw.tiles.length > 65536) throw new Error("Invalid tileset");
-    return { ...raw, tiles: raw.tiles.map((t) => {
-      const data = files[t.member];
-      if (!data) throw new Error("Missing tile member");
-      return { ...t, data };
-    }) };
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Invalid tileset");
+    const tileset = raw;
+    if (!Array.isArray(tileset.tiles) || tileset.tiles.length > 65536) throw new Error("Invalid tileset");
+    return {
+      ...tileset,
+      tiles: tileset.tiles.map((rawTile) => {
+        if (!rawTile || typeof rawTile !== "object" || Array.isArray(rawTile)) throw new Error("Invalid tile");
+        const tile = rawTile;
+        const member = typeof tile.member === "string" ? tile.member : "";
+        if (!member.startsWith("tiles/") || !Object.hasOwn(files, member)) throw new Error("Missing tile member");
+        return { ...tile, data: files[member] };
+      })
+    };
   });
   const candidate = { ...projectRaw, images, tilesets };
-  return validateProjectShape(candidate);
+  const project = validateProjectShape(candidate);
+  validateProject(project);
+  return project;
 }
 
 // packages/codecs/src/zlib.ts
@@ -2779,13 +2798,13 @@ function importGIF(bytes, name = "Imported GIF") {
 }
 
 export {
-  ByteReader,
-  ByteWriter,
-  crc32,
   makeImage,
   imageHash,
   LIMITS,
   validateProjectShape,
+  ByteReader,
+  ByteWriter,
+  crc32,
   saveNative,
   loadNative,
   deflateSync,

package/lib/core.d.ts

@@ -1,5 +1,5 @@
-import { g as Project, F as Frame, L as Layer, T as Tag, R as RGBA, I as ImageDataModel, M as Mode, C as Cel, h as Rect, m as Tool, f as Point, P as PaintOptions, B as Blend } from './types/types-DV6m_OJI.js';
-export { A as AtlasOptions, a as AtlasRecord, b as AtlasResult, D as Diagnostic, c as Direction, d as Ink, e as PaletteKey, S as Slice, i as SliceKey, j as TileCell, k as TileMap, l as TileSet } from './types/types-DV6m_OJI.js';
+import { P as Project, F as Frame, L as Layer, T as Tag, R as RGBA, I as ImageDataModel, M as Mode, C as Cel, h as Rect, m as Tool, g as Point, e as PaintOptions, B as Blend } from './types/types-Bzr7gnEZ.js';
+export { A as AtlasOptions, a as AtlasRecord, b as AtlasResult, D as Diagnostic, c as Direction, d as Ink, f as PaletteKey, S as Slice, i as SliceKey, j as TileCell, k as TileMap, l as TileSet } from './types/types-Bzr7gnEZ.js';
 
 /** Stable unique id generator (crypto UUID when available). */
 declare function uid(): string;

package/lib/index.d.ts

@@ -1,3 +1,14 @@
-export { A as AtlasOptions, a as AtlasRecord, b as AtlasResult, B as Blend, C as Cel, D as Diagnostic, c as Direction, F as Frame, I as ImageDataModel, d as Ink, L as Layer, M as Mode, P as PaintOptions, e as PaletteKey, f as Point, g as Project, R as RGBA, h as Rect, S as Slice, i as SliceKey, T as Tag, j as TileCell, k as TileMap, l as TileSet, m as Tool } from './types/types-DV6m_OJI.js';
+import { P as Project } from './types/types-Bzr7gnEZ.js';
+export { A as AtlasOptions, a as AtlasRecord, b as AtlasResult, B as Blend, C as Cel, D as Diagnostic, c as Direction, F as Frame, I as ImageDataModel, d as Ink, L as Layer, M as Mode, e as PaintOptions, f as PaletteKey, g as Point, R as RGBA, h as Rect, S as Slice, i as SliceKey, T as Tag, j as TileCell, k as TileMap, l as TileSet, m as Tool } from './types/types-Bzr7gnEZ.js';
 export { AdjustmentKind, AdjustmentOptions, AdvancedTransformOptions, CustomBrush, DEFAULT_DYNAMICS, Dynamics, History, SUPPORTED_BLENDS, StrokeSample, addFrame, addLayer, addTag, adjust, animationSequence, applyAdjustment, blendPixel, boundsOfSelection, brushFromJSON, brushToJSON, captureBrush, cloneImage, cloneImageWithId, cloneProject, combineSelection, compositePixel, convertMode, createProject, cropBuffer, currentBackgroundColor, editTile, effectiveLocked, effectiveVisible, ensureCel, getCel, growSelection, imagePixelsRGBA, imageRGBA, imageToRGBA, isEmptySelection, isSupportedBlend, linkCel, makeEllipseSelection, makePolygonSelection, makeSelection, moveCel, paint, paintDynamic, paletteFor, rasterOverlay, removeFrame, removeLayer, renderFrame, renderOnion, reorderLayer, resizeProject, rgbaToGray, shrinkSelection, strokeStamps, transformAdvanced, transformCel, uid, unlinkCel, validateBrush, validateProject, wandSelection } from './core.js';
 export { ByteReader, ByteWriter, EncodeASEResult, GifEncodeOptions, LIMITS, imageToRGBA as codecImageToRGBA, crc32, createAtlas, decodeASE, decodeGIF, decodePNG, deflateSync, encodeASE, encodeGIF, encodeGIFDetailed, encodePNG, exportMetadata, frameToRGBA, imageHash, importGIF, inflateReusable, loadNative, makeImage, planGIFAnimation, saveNative, validateProjectShape, verifyPNG } 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

@@ -25,7 +25,7 @@ import {
   saveNative,
   validateProjectShape,
   verifyPNG
-} from "./chunks/chunk-DBS4XKWD.js";
+} from "./chunks/chunk-DVGCTRCE.js";
 import {
   DEFAULT_DYNAMICS,
   History,
@@ -87,6 +87,45 @@ import {
   validateProject,
   wandSelection
 } from "./chunks/chunk-NUS76ZK4.js";
+
+// sdk/editor.ts
+function normalize(project) {
+  const candidate = validateProjectShape(structuredClone(project));
+  validateProject(candidate);
+  return candidate;
+}
+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 {
   ByteReader,
   ByteWriter,
@@ -114,6 +153,7 @@ export {
   convertMode,
   crc32,
   createAtlas,
+  createHeadlessEditor,
   createProject,
   cropBuffer,
   currentBackgroundColor,

package/lib/io.js

@@ -24,7 +24,7 @@ import {
   saveNative,
   validateProjectShape,
   verifyPNG
-} from "./chunks/chunk-DBS4XKWD.js";
+} from "./chunks/chunk-DVGCTRCE.js";
 import "./chunks/chunk-NUS76ZK4.js";
 export {
   ByteReader,

package/lib/types/{types-DV6m_OJI.d.ts → types-Bzr7gnEZ.d.ts}

@@ -192,4 +192,4 @@ interface AtlasResult {
     meta: Record<string, unknown>;
 }
 
-export type { AtlasOptions as A, Blend as B, Cel as C, Diagnostic as D, Frame as F, ImageDataModel as I, Layer as L, Mode as M, PaintOptions as P, RGBA as R, Slice as S, Tag as T, AtlasRecord as a, AtlasResult as b, Direction as c, Ink as d, PaletteKey as e, Point as f, Project as g, Rect as h, SliceKey as i, TileCell as j, TileMap as k, TileSet as l, Tool as m };
+export type { AtlasOptions as A, Blend as B, Cel as C, Diagnostic as D, Frame as F, ImageDataModel as I, Layer as L, Mode as M, Project as P, RGBA as R, Slice as S, Tag as T, AtlasRecord as a, AtlasResult as b, Direction as c, Ink as d, PaintOptions as e, PaletteKey as f, Point as g, Rect as h, SliceKey as i, TileCell as j, TileMap as k, TileSet as l, Tool as m };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bookklik/pivo-craft",
   "description": "A local-first browser pixel-art and animation editor.",
-  "version": "0.6.0",
+  "version": "0.6.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",
     "typecheck": "tsc --noEmit",
     "docs:dev": "npm run docs:build && node scripts/preview-docs.mjs",
     "docs:build": "vitepress build docs",
@@ -114,6 +115,8 @@
     "editor"
   ],
   "overrides": {
+    "glob": "14.0.3",
+    "minimatch": "11.0.1",
     "fast-uri": "3.1.9",
     "serialize-javascript": "7.1.3",
     "vitepress": {