pixelkiln 0.26.0 → 0.28.0

package/dist/index.d.cts

@@ -7543,8 +7543,11 @@ type GalleryState = PlanState | "undeclared";
 interface GalleryMedia {
     /** Absolute path of the file the server may read for this id. */
     path: string;
-    contentType: MediaType;
+    /** Images, or the editor's own project file kept beside a browser edit. */
+    contentType: MediaType | typeof PROJECT_FILE_TYPE;
 }
+/** Served type of a Pixelorama `.pxo`: a zip the browser never renders. */
+declare const PROJECT_FILE_TYPE = "application/octet-stream";
 interface GalleryOutput {
     /** Manifest-relative path as recorded (or as the manifest would record it). */
     path: string;
@@ -7671,6 +7674,8 @@ interface GalleryItem {
      */
     edit: GalleryOutput | null;
     editStatus: HandEditStatus | null;
+    /** What an in-browser save recorded beside the edit; null for edits made elsewhere. */
+    editMeta: GalleryEditMeta | null;
     /** Where the provider's own app shows this object, when it has one. */
     upstreamUrl: string | null;
     /** Downloaded work with a durable provider reference; `fetch --refresh` can re-pull it. */
@@ -7786,6 +7791,23 @@ interface BuildGalleryOptions {
 /** Route id for one absolute path: stable across refreshes, not enumerable. */
 declare function galleryMediaId(absolutePath: string): string;
 declare function galleryMediaRoute(id: string): string;
+/**
+ * Build the gallery from the project's offline state. `specs` are the resolved
+ * (possibly filtered) manifest entries the CLI already computed; lock entries
+ * outside the manifest are added here so paid work is never hidden.
+ */
+interface GalleryEditMeta {
+    editor: string;
+    savedAt: string;
+    /** sha256 of the generation the edit was based on, or null for untracked art. */
+    basedOn: string | null;
+    /** The edit file changed since the editor saved it (another tool touched it). */
+    changedSince: boolean;
+    /** Manifest-relative path of the layered project file kept beside the edit, if present. */
+    project: string | null;
+    /** Where the page fetches that file to hand it back to the editor; null without one. */
+    projectUrl: string | null;
+}
 declare function buildGallerySnapshot(opts: BuildGalleryOptions): Promise<GalleryBuild>;
 interface BuildWorkspaceGalleryOptions {
     workspace: Workspace;
@@ -7832,6 +7854,8 @@ interface RenderGalleryOptions {
     editable?: boolean;
     /** Generation jobs are enabled (`--budget`). */
     generation?: boolean;
+    /** The in-browser editor can be installed and served (`--edit` without `--no-editor`). */
+    editor?: boolean;
 }
 declare function renderGallery(snapshot: GallerySnapshot, opts?: RenderGalleryOptions): string;
 
@@ -8248,12 +8272,81 @@ interface GalleryEditHandlerOptions {
 /** The `edit` callback `serveGallery` expects: validate, apply, rebuild. */
 declare function createGalleryEditHandler(opts: GalleryEditHandlerOptions): (body: unknown) => Promise<GalleryBuild>;
 
+/**
+ * The in-gallery editor is a 46 MB web build that is not part of the npm
+ * package. It is fetched once per pinned release into a user-level cache,
+ * every file verified against the hash the package carries, and served from
+ * there by the gallery. Nothing is executed at install; the browser runs the
+ * wasm, and only from files whose hashes matched.
+ *
+ * A user-level cache rather than the project's `.pixelkiln/`: the pin is per
+ * PixelKiln release, not per project, and one copy serves every project.
+ * `PIXELKILN_TOOLS_DIR` moves it; `PIXELKILN_EDITOR_URL` points downloads at
+ * a mirror or a local directory server for offline machines.
+ */
+interface EditorInstallStatus {
+    /** Release tag the package pins; null means no build has been published for this version. */
+    release: string | null;
+    dir: string;
+    /** Every pinned file is present with the right hash. */
+    installed: boolean;
+    /** Files still to fetch (missing or hash mismatch). */
+    missing: string[];
+    totalBytes: number;
+    installedBytes: number;
+}
+interface EditorInstallProgress {
+    file: string;
+    index: number;
+    count: number;
+    bytes: number;
+    totalBytes: number;
+    /** Bytes fetched so far across all files, including the part of this one. */
+    fetchedBytes: number;
+    /** `start` once per file, `progress` as its bytes arrive, `done` once it verified and landed. */
+    phase: "start" | "progress" | "done";
+}
+
+/**
+ * The gallery's side of the in-browser editor: it reports whether the pinned
+ * build is on disk, installs it on request, and serves its files.
+ *
+ * Serving is allowlisted twice. The release tag in the URL must be the one
+ * this package pins, and the file name must be one the pin lists; nothing
+ * else under the tools directory is reachable. A file is served only after
+ * the whole build has verified against the pinned hashes, and its size is
+ * checked again on every read, so a build that changed on disk after
+ * verification is refused rather than served.
+ */
+interface GalleryEditorStatus extends EditorInstallStatus {
+    pixelorama: string;
+    protocol: number;
+    /** Where the page loads the editor from once installed; null until then. */
+    url: string | null;
+    /** The install in flight, if any. */
+    installing: EditorInstallProgress | null;
+    /** Why the last install failed, until the next attempt. */
+    error: string | null;
+}
+interface GalleryEditorHandlers {
+    release: string | null;
+    status(): Promise<GalleryEditorStatus>;
+    /** Start an install unless one is running; returns the status right after. */
+    install(): Promise<GalleryEditorStatus>;
+    /** A verified build file, or null when it is not pinned or not installed. */
+    file(release: string, name: string): Promise<{
+        bytes: Buffer;
+        contentType: string;
+    } | null>;
+}
+
 /**
  * The gallery's HTTP surface. Unlike the review server this is long-lived:
  * three GET routes, bound to loopback, running until the caller closes it
  * (the CLI does so on Ctrl+C). It has no write path unless the caller opts
- * in: `edit` adds one POST route for manifest edits, and `generate` adds the
- * routes that start a generation job and host its review sheet.
+ * in: `edit` adds one POST route for manifest edits, `generate` adds the
+ * routes that start a generation job and host its review sheet, and `editor`
+ * adds the routes that install and serve the in-browser pixel editor.
  *
  * Every POST is guarded twice, because a page on localhost is reachable by
  * every other page in the browser: the request's Origin must be this server,
@@ -8288,6 +8381,11 @@ interface GalleryServerOptions {
      * sheet. The handlers own budgets and provider access; see `generate.ts`.
      */
     generate?: GalleryGenerateHandlers;
+    /**
+     * Enable `GET /api/editor`, `POST /api/editor/install`, and the static
+     * `/editor/<release>/<file>` routes that serve the pinned editor build.
+     */
+    editor?: GalleryEditorHandlers;
 }
 interface GalleryServer {
     url: string;

package/dist/index.d.ts

@@ -7543,8 +7543,11 @@ type GalleryState = PlanState | "undeclared";
 interface GalleryMedia {
     /** Absolute path of the file the server may read for this id. */
     path: string;
-    contentType: MediaType;
+    /** Images, or the editor's own project file kept beside a browser edit. */
+    contentType: MediaType | typeof PROJECT_FILE_TYPE;
 }
+/** Served type of a Pixelorama `.pxo`: a zip the browser never renders. */
+declare const PROJECT_FILE_TYPE = "application/octet-stream";
 interface GalleryOutput {
     /** Manifest-relative path as recorded (or as the manifest would record it). */
     path: string;
@@ -7671,6 +7674,8 @@ interface GalleryItem {
      */
     edit: GalleryOutput | null;
     editStatus: HandEditStatus | null;
+    /** What an in-browser save recorded beside the edit; null for edits made elsewhere. */
+    editMeta: GalleryEditMeta | null;
     /** Where the provider's own app shows this object, when it has one. */
     upstreamUrl: string | null;
     /** Downloaded work with a durable provider reference; `fetch --refresh` can re-pull it. */
@@ -7786,6 +7791,23 @@ interface BuildGalleryOptions {
 /** Route id for one absolute path: stable across refreshes, not enumerable. */
 declare function galleryMediaId(absolutePath: string): string;
 declare function galleryMediaRoute(id: string): string;
+/**
+ * Build the gallery from the project's offline state. `specs` are the resolved
+ * (possibly filtered) manifest entries the CLI already computed; lock entries
+ * outside the manifest are added here so paid work is never hidden.
+ */
+interface GalleryEditMeta {
+    editor: string;
+    savedAt: string;
+    /** sha256 of the generation the edit was based on, or null for untracked art. */
+    basedOn: string | null;
+    /** The edit file changed since the editor saved it (another tool touched it). */
+    changedSince: boolean;
+    /** Manifest-relative path of the layered project file kept beside the edit, if present. */
+    project: string | null;
+    /** Where the page fetches that file to hand it back to the editor; null without one. */
+    projectUrl: string | null;
+}
 declare function buildGallerySnapshot(opts: BuildGalleryOptions): Promise<GalleryBuild>;
 interface BuildWorkspaceGalleryOptions {
     workspace: Workspace;
@@ -7832,6 +7854,8 @@ interface RenderGalleryOptions {
     editable?: boolean;
     /** Generation jobs are enabled (`--budget`). */
     generation?: boolean;
+    /** The in-browser editor can be installed and served (`--edit` without `--no-editor`). */
+    editor?: boolean;
 }
 declare function renderGallery(snapshot: GallerySnapshot, opts?: RenderGalleryOptions): string;
 
@@ -8248,12 +8272,81 @@ interface GalleryEditHandlerOptions {
 /** The `edit` callback `serveGallery` expects: validate, apply, rebuild. */
 declare function createGalleryEditHandler(opts: GalleryEditHandlerOptions): (body: unknown) => Promise<GalleryBuild>;
 
+/**
+ * The in-gallery editor is a 46 MB web build that is not part of the npm
+ * package. It is fetched once per pinned release into a user-level cache,
+ * every file verified against the hash the package carries, and served from
+ * there by the gallery. Nothing is executed at install; the browser runs the
+ * wasm, and only from files whose hashes matched.
+ *
+ * A user-level cache rather than the project's `.pixelkiln/`: the pin is per
+ * PixelKiln release, not per project, and one copy serves every project.
+ * `PIXELKILN_TOOLS_DIR` moves it; `PIXELKILN_EDITOR_URL` points downloads at
+ * a mirror or a local directory server for offline machines.
+ */
+interface EditorInstallStatus {
+    /** Release tag the package pins; null means no build has been published for this version. */
+    release: string | null;
+    dir: string;
+    /** Every pinned file is present with the right hash. */
+    installed: boolean;
+    /** Files still to fetch (missing or hash mismatch). */
+    missing: string[];
+    totalBytes: number;
+    installedBytes: number;
+}
+interface EditorInstallProgress {
+    file: string;
+    index: number;
+    count: number;
+    bytes: number;
+    totalBytes: number;
+    /** Bytes fetched so far across all files, including the part of this one. */
+    fetchedBytes: number;
+    /** `start` once per file, `progress` as its bytes arrive, `done` once it verified and landed. */
+    phase: "start" | "progress" | "done";
+}
+
+/**
+ * The gallery's side of the in-browser editor: it reports whether the pinned
+ * build is on disk, installs it on request, and serves its files.
+ *
+ * Serving is allowlisted twice. The release tag in the URL must be the one
+ * this package pins, and the file name must be one the pin lists; nothing
+ * else under the tools directory is reachable. A file is served only after
+ * the whole build has verified against the pinned hashes, and its size is
+ * checked again on every read, so a build that changed on disk after
+ * verification is refused rather than served.
+ */
+interface GalleryEditorStatus extends EditorInstallStatus {
+    pixelorama: string;
+    protocol: number;
+    /** Where the page loads the editor from once installed; null until then. */
+    url: string | null;
+    /** The install in flight, if any. */
+    installing: EditorInstallProgress | null;
+    /** Why the last install failed, until the next attempt. */
+    error: string | null;
+}
+interface GalleryEditorHandlers {
+    release: string | null;
+    status(): Promise<GalleryEditorStatus>;
+    /** Start an install unless one is running; returns the status right after. */
+    install(): Promise<GalleryEditorStatus>;
+    /** A verified build file, or null when it is not pinned or not installed. */
+    file(release: string, name: string): Promise<{
+        bytes: Buffer;
+        contentType: string;
+    } | null>;
+}
+
 /**
  * The gallery's HTTP surface. Unlike the review server this is long-lived:
  * three GET routes, bound to loopback, running until the caller closes it
  * (the CLI does so on Ctrl+C). It has no write path unless the caller opts
- * in: `edit` adds one POST route for manifest edits, and `generate` adds the
- * routes that start a generation job and host its review sheet.
+ * in: `edit` adds one POST route for manifest edits, `generate` adds the
+ * routes that start a generation job and host its review sheet, and `editor`
+ * adds the routes that install and serve the in-browser pixel editor.
  *
  * Every POST is guarded twice, because a page on localhost is reachable by
  * every other page in the browser: the request's Origin must be this server,
@@ -8288,6 +8381,11 @@ interface GalleryServerOptions {
      * sheet. The handlers own budgets and provider access; see `generate.ts`.
      */
     generate?: GalleryGenerateHandlers;
+    /**
+     * Enable `GET /api/editor`, `POST /api/editor/install`, and the static
+     * `/editor/<release>/<file>` routes that serve the pinned editor build.
+     */
+    editor?: GalleryEditorHandlers;
 }
 interface GalleryServer {
     url: string;