@openfairygui/functions 0.2.0-alpha.8 → 0.2.0

package/README.md

@@ -11,19 +11,55 @@ npm install --save @openfairygui/core @openfairygui/functions
 ## Usage
 
 ```ts
-import { NodeIO } from '@openfairygui/core';
-import { inspect, publish } from '@openfairygui/functions';
+import { NodeIO } from '@openfairygui/core/node';
+import { inspect } from '@openfairygui/functions';
+import { publishNode, restoreNode } from '@openfairygui/functions/node';
 
 const io = new NodeIO();
 const doc = await io.readProject('./MyProject/MyProject.fairy');
 
 const report = inspect(doc);
-await doc.transform(publish({ output: './release' }));
+await publishNode({ document: doc, output: './release' });
+
+await restoreNode({
+	inputDir: './release',
+	output: './restored-project',
+});
+```
+
+`publishNode` owns the standard Node filesystem, Sharp raster backend, and project plugin discovery. `restoreNode` owns the Node filesystem and Sharp image extraction required by trusted-local artifact recovery. The root `publish()` and `restore()` exports remain the lower-level capability-injected workflows for custom hosts.
+
+## Browser LayaBox publish
+
+Use `@openfairygui/core/web` to read the raw project, then publish through the browser-only entry. Both filesystems are caller-owned, so they can be File System Access, OPFS, IndexedDB, ZIP, or memory adapters.
+
+```ts
+import { WebIO } from '@openfairygui/core/web';
+import { publishBrowser } from '@openfairygui/functions/web';
+
+const document = await new WebIO(sourceFileSystem).readProject('Project.fairy');
+const result = await publishBrowser({
+	document,
+	sourceFileSystem,
+	outputFileSystem,
+	projectType: 'layabox',
+	output: '.fairygui-runtime',
+});
+
+if (!result.success) console.error(result.diagnostics);
 ```
 
-## Phase A UAM authoring seam
+The browser entry uses native Canvas APIs for atlas PNGs, writes only through `outputFileSystem`, and supplies no Node plugin capability. Persisted Laya publish compression, atlas, and safe file-extension settings apply; explicit `compressed` and `atlas` options override their corresponding settings. Explicit `output`, `branch`, and `packages` also keep their normal precedence, so desktop-only configured output paths are not used when `output` is supplied.
+
+Browser code generation is not supported. If global code generation is enabled and a selected package requests it, preflight returns `unsupported_publish_setting` with `setting` and `path` before Canvas checks or output writes. On any failure, `files` lists only `writeFileRaw` operations that completed successfully; `success: false` with a non-empty list therefore means built-in output is partial. Callers needing atomic publication should provide a transactional or staging `outputFileSystem`.
+
+Publish plugins are documented in the repository guide:
 
-`@openfairygui/functions` also exposes a thin stateless wrapper over the Phase A UAM
+- https://github.com/OpenFairyGUI/OpenFairyGUI/blob/main/docs/publish-plugins.md
+
+## UAM authoring seam
+
+`@openfairygui/functions` also exposes a thin stateless wrapper over the UAM
 transaction contract from `@openfairygui/core`.
 
 This seam:
@@ -34,6 +70,16 @@ This seam:
 - does not define a second selector / operation grammar
 - does not wrap `publish` or `restore`
 
+The transaction surface includes component size/root properties, component-instance
+extension overlays, resource rename/move, complete image-resource property snapshots,
+byte-backed binary resource add/replace/remove,
+and add/update/remove for `display`, `display2`, `look`, `xy`, `size`, `color`,
+`animation`, `text`, `icon`, and `fontSize` gears. Resource
+rename/move/replace/remove requires `sourceBytes`; opt in with
+`ProjectReader.read(path, { hydrateResourceBytes: true })` before lifting a project to
+UAM. Source bytes are written back with the project, and stale source files are removed
+only after all replacement content succeeds.
+
 ```ts
 import {
 	type UamProject,
@@ -41,7 +87,7 @@ import {
 } from '@openfairygui/core';
 import { applyUamTransactionApp } from '@openfairygui/functions';
 
-const project: UamProject = /* ... */;
+const project: UamProject = /* project read and lifted with hydrateResourceBytes */;
 const operations: UamTransactionOperation[] = [
 	{
 		kind: 'renameResource',

package/dist/atlas-C6tbl7nn.d.ts

@@ -0,0 +1,193 @@
+import { FileSystem, Transform } from "@openfairygui/core";
+
+//#region src/publish/contracts.d.ts
+/**
+ * Source files required by a publish adapter.
+ *
+ * The host owns this filesystem: Node adapters use native paths while web
+ * adapters can use File System Access, OPFS, IndexedDB, ZIP, or memory.
+ */
+type PublishSourceFileSystem = Pick<FileSystem, 'readFileRaw' | 'join'>;
+/**
+ * Output files required by a publish adapter.
+ */
+type PublishOutputFileSystem = Pick<FileSystem, 'writeFileRaw' | 'mkdir' | 'join'>;
+/**
+ * Full filesystem contract consumed by the capability-injected publish core.
+ *
+ * Read, enumeration, and delete operations are optional because individual
+ * publish lanes only request them when needed.
+ */
+type PublishFileSystem = PublishOutputFileSystem & {
+  deleteFile?: (path: string) => Promise<void>;
+  exists?: FileSystem['exists'];
+  readdir?: FileSystem['readdir'];
+  readFileRaw?: FileSystem['readFileRaw'];
+};
+interface AtlasRasterMetadata {
+  width?: number;
+  height?: number;
+  channels?: number;
+  hasAlpha?: boolean;
+  trimOffsetLeft?: number;
+  trimOffsetTop?: number;
+}
+interface AtlasRasterResolvedBuffer {
+  data: Uint8Array;
+  info: Required<Pick<AtlasRasterMetadata, 'width' | 'height' | 'channels'>> & AtlasRasterMetadata;
+}
+interface AtlasRasterCompositeInput {
+  input: Uint8Array;
+  left: number;
+  top: number;
+}
+type AtlasRasterInput = string | Uint8Array | {
+  create: {
+    width: number;
+    height: number;
+    channels: 4;
+    background: {
+      r: number;
+      g: number;
+      b: number;
+      alpha: number;
+    };
+  };
+};
+/**
+ * Host-provided raster pipeline used by atlas packing.
+ *
+ * Sharp and the browser Canvas adapter both satisfy this contract.
+ */
+interface AtlasRasterPipeline {
+  ensureAlpha(): AtlasRasterPipeline;
+  resize(options: {
+    width: number;
+    height: number;
+    fit?: 'fill';
+  }): AtlasRasterPipeline;
+  raw(): AtlasRasterPipeline;
+  extract(options: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  }): AtlasRasterPipeline;
+  png(): AtlasRasterPipeline;
+  rotate(angle: number): AtlasRasterPipeline;
+  composite(inputs: AtlasRasterCompositeInput[]): AtlasRasterPipeline;
+  metadata(): Promise<AtlasRasterMetadata>;
+  toBuffer(options: {
+    resolveWithObject: true;
+  }): Promise<AtlasRasterResolvedBuffer>;
+  toBuffer(options?: {
+    resolveWithObject?: false;
+  }): Promise<Uint8Array>;
+  toFile(path: string): Promise<unknown>;
+}
+type AtlasRasterBackend = (input: AtlasRasterInput) => AtlasRasterPipeline;
+//#endregion
+//#region src/atlas.d.ts
+interface AtlasOptions {
+  /**
+   * Limit atlas generation to specific package names.
+   * When omitted, all packages are processed.
+   */
+  packages?: string[];
+  /**
+   * Raster backend, injected by the host adapter.
+   * Required for actual image compositing and trimImage.
+   *
+   * ```ts
+   * import sharp from 'sharp';
+   * await doc.transform(atlas({ encoder: sharp }));
+   * ```
+   */
+  encoder?: AtlasRasterBackend;
+  /** Maximum atlas texture size (width and height). Default: 2048. */
+  maxSize?: number;
+  /** Whether to use the fast editor-compatible packing heuristics. Default: true. */
+  fast?: boolean;
+  /** Allow rotating sprites 90° for better packing. Default: true. */
+  allowRotation?: boolean;
+  /** Pixel padding between sprites. Default: 1. */
+  padding?: number;
+  /** Constrain atlas dimensions to powers of two. Default: false. */
+  powerOfTwo?: boolean;
+  /** Force square atlas (width === height). Default: false. */
+  square?: boolean;
+  /** Allow spilling into multiple atlas pages. Default: true. */
+  multiPage?: boolean;
+  /**
+   * Trim transparent pixels from image edges before packing.
+   * Requires a raster backend. Stores offset/originalSize in Sprite nodes.
+   * Default: false.
+   */
+  trimImage?: boolean;
+  /**
+   * Base path for reading source images. If not set, images must have
+   * their pixel data stored in extras._imageData as Uint8Array.
+   */
+  basePath?: string;
+  /**
+   * Output directory for generated atlas PNGs.
+   * Required when encoder is provided.
+   */
+  outputPath?: string;
+  /**
+   * Optional mkdir function to ensure output directory exists.
+   * If not provided, the outputPath directory must already exist.
+   */
+  mkdir?: (path: string) => Promise<void>;
+  /**
+   * Optional raw file reader for reading .jta MovieClip files.
+   * Required for MovieClip frame atlas packing.
+   */
+  readFileRaw?: (path: string) => Promise<Uint8Array>;
+  /**
+   * Keep original input order when MaxRects tie-break scores are equal.
+   * This is an internal publish detail used to mirror editor/CLI behavior.
+   */
+  preserveInputOrderOnTie?: boolean;
+  /**
+   * Internal publish detail used by Unity binary output:
+   * allow single untrimmed PNG image packages to bypass the packer and
+   * write atlas0 directly, matching the reference CLI behavior.
+   */
+  directSingleImageOutput?: boolean;
+  /**
+   * Internal publish detail used by the direct-image-output path.
+   * When extractAlpha is enabled, the direct output shortcut must be disabled.
+   */
+  extractAlpha?: boolean;
+  /**
+   * When branchProcessing keeps branch resources, publish branch images into
+   * separate atlas pages/files per branch instead of mixing them with main.
+   */
+  separatedAtlasForBranch?: boolean;
+}
+/**
+ * Packs image resources into texture atlases.
+ *
+ * This transform performs MaxRects bin-packing on all ImageResource items
+ * within each package, creating Atlas and Sprite property nodes. When an
+ * a raster backend is provided, it also composites the actual PNG files.
+ *
+ * When `trimImage` is enabled and encoder is available, transparent pixels
+ * at image edges are trimmed before packing. The trimmed offset and original
+ * dimensions are stored in the Sprite nodes for runtime reconstruction.
+ *
+ * ```ts
+ * import sharp from 'sharp';
+ * await doc.transform(atlas({
+ *   encoder: sharp,
+ *   maxSize: 2048,
+ *   trimImage: true,
+ *   basePath: './assets/',
+ *   outputPath: './dist/',
+ * }));
+ * ```
+ */
+declare function atlas(_options?: AtlasOptions): Transform;
+//#endregion
+export { AtlasRasterInput as a, AtlasRasterResolvedBuffer as c, PublishSourceFileSystem as d, AtlasRasterCompositeInput as i, PublishFileSystem as l, atlas as n, AtlasRasterMetadata as o, AtlasRasterBackend as r, AtlasRasterPipeline as s, AtlasOptions as t, PublishOutputFileSystem as u };

package/dist/atlas-CHsu2Y8i.d.cts

@@ -0,0 +1,193 @@
+import { FileSystem, Transform } from "@openfairygui/core";
+
+//#region src/publish/contracts.d.ts
+/**
+ * Source files required by a publish adapter.
+ *
+ * The host owns this filesystem: Node adapters use native paths while web
+ * adapters can use File System Access, OPFS, IndexedDB, ZIP, or memory.
+ */
+type PublishSourceFileSystem = Pick<FileSystem, 'readFileRaw' | 'join'>;
+/**
+ * Output files required by a publish adapter.
+ */
+type PublishOutputFileSystem = Pick<FileSystem, 'writeFileRaw' | 'mkdir' | 'join'>;
+/**
+ * Full filesystem contract consumed by the capability-injected publish core.
+ *
+ * Read, enumeration, and delete operations are optional because individual
+ * publish lanes only request them when needed.
+ */
+type PublishFileSystem = PublishOutputFileSystem & {
+  deleteFile?: (path: string) => Promise<void>;
+  exists?: FileSystem['exists'];
+  readdir?: FileSystem['readdir'];
+  readFileRaw?: FileSystem['readFileRaw'];
+};
+interface AtlasRasterMetadata {
+  width?: number;
+  height?: number;
+  channels?: number;
+  hasAlpha?: boolean;
+  trimOffsetLeft?: number;
+  trimOffsetTop?: number;
+}
+interface AtlasRasterResolvedBuffer {
+  data: Uint8Array;
+  info: Required<Pick<AtlasRasterMetadata, 'width' | 'height' | 'channels'>> & AtlasRasterMetadata;
+}
+interface AtlasRasterCompositeInput {
+  input: Uint8Array;
+  left: number;
+  top: number;
+}
+type AtlasRasterInput = string | Uint8Array | {
+  create: {
+    width: number;
+    height: number;
+    channels: 4;
+    background: {
+      r: number;
+      g: number;
+      b: number;
+      alpha: number;
+    };
+  };
+};
+/**
+ * Host-provided raster pipeline used by atlas packing.
+ *
+ * Sharp and the browser Canvas adapter both satisfy this contract.
+ */
+interface AtlasRasterPipeline {
+  ensureAlpha(): AtlasRasterPipeline;
+  resize(options: {
+    width: number;
+    height: number;
+    fit?: 'fill';
+  }): AtlasRasterPipeline;
+  raw(): AtlasRasterPipeline;
+  extract(options: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  }): AtlasRasterPipeline;
+  png(): AtlasRasterPipeline;
+  rotate(angle: number): AtlasRasterPipeline;
+  composite(inputs: AtlasRasterCompositeInput[]): AtlasRasterPipeline;
+  metadata(): Promise<AtlasRasterMetadata>;
+  toBuffer(options: {
+    resolveWithObject: true;
+  }): Promise<AtlasRasterResolvedBuffer>;
+  toBuffer(options?: {
+    resolveWithObject?: false;
+  }): Promise<Uint8Array>;
+  toFile(path: string): Promise<unknown>;
+}
+type AtlasRasterBackend = (input: AtlasRasterInput) => AtlasRasterPipeline;
+//#endregion
+//#region src/atlas.d.ts
+interface AtlasOptions {
+  /**
+   * Limit atlas generation to specific package names.
+   * When omitted, all packages are processed.
+   */
+  packages?: string[];
+  /**
+   * Raster backend, injected by the host adapter.
+   * Required for actual image compositing and trimImage.
+   *
+   * ```ts
+   * import sharp from 'sharp';
+   * await doc.transform(atlas({ encoder: sharp }));
+   * ```
+   */
+  encoder?: AtlasRasterBackend;
+  /** Maximum atlas texture size (width and height). Default: 2048. */
+  maxSize?: number;
+  /** Whether to use the fast editor-compatible packing heuristics. Default: true. */
+  fast?: boolean;
+  /** Allow rotating sprites 90° for better packing. Default: true. */
+  allowRotation?: boolean;
+  /** Pixel padding between sprites. Default: 1. */
+  padding?: number;
+  /** Constrain atlas dimensions to powers of two. Default: false. */
+  powerOfTwo?: boolean;
+  /** Force square atlas (width === height). Default: false. */
+  square?: boolean;
+  /** Allow spilling into multiple atlas pages. Default: true. */
+  multiPage?: boolean;
+  /**
+   * Trim transparent pixels from image edges before packing.
+   * Requires a raster backend. Stores offset/originalSize in Sprite nodes.
+   * Default: false.
+   */
+  trimImage?: boolean;
+  /**
+   * Base path for reading source images. If not set, images must have
+   * their pixel data stored in extras._imageData as Uint8Array.
+   */
+  basePath?: string;
+  /**
+   * Output directory for generated atlas PNGs.
+   * Required when encoder is provided.
+   */
+  outputPath?: string;
+  /**
+   * Optional mkdir function to ensure output directory exists.
+   * If not provided, the outputPath directory must already exist.
+   */
+  mkdir?: (path: string) => Promise<void>;
+  /**
+   * Optional raw file reader for reading .jta MovieClip files.
+   * Required for MovieClip frame atlas packing.
+   */
+  readFileRaw?: (path: string) => Promise<Uint8Array>;
+  /**
+   * Keep original input order when MaxRects tie-break scores are equal.
+   * This is an internal publish detail used to mirror editor/CLI behavior.
+   */
+  preserveInputOrderOnTie?: boolean;
+  /**
+   * Internal publish detail used by Unity binary output:
+   * allow single untrimmed PNG image packages to bypass the packer and
+   * write atlas0 directly, matching the reference CLI behavior.
+   */
+  directSingleImageOutput?: boolean;
+  /**
+   * Internal publish detail used by the direct-image-output path.
+   * When extractAlpha is enabled, the direct output shortcut must be disabled.
+   */
+  extractAlpha?: boolean;
+  /**
+   * When branchProcessing keeps branch resources, publish branch images into
+   * separate atlas pages/files per branch instead of mixing them with main.
+   */
+  separatedAtlasForBranch?: boolean;
+}
+/**
+ * Packs image resources into texture atlases.
+ *
+ * This transform performs MaxRects bin-packing on all ImageResource items
+ * within each package, creating Atlas and Sprite property nodes. When an
+ * a raster backend is provided, it also composites the actual PNG files.
+ *
+ * When `trimImage` is enabled and encoder is available, transparent pixels
+ * at image edges are trimmed before packing. The trimmed offset and original
+ * dimensions are stored in the Sprite nodes for runtime reconstruction.
+ *
+ * ```ts
+ * import sharp from 'sharp';
+ * await doc.transform(atlas({
+ *   encoder: sharp,
+ *   maxSize: 2048,
+ *   trimImage: true,
+ *   basePath: './assets/',
+ *   outputPath: './dist/',
+ * }));
+ * ```
+ */
+declare function atlas(_options?: AtlasOptions): Transform;
+//#endregion
+export { AtlasRasterInput as a, AtlasRasterResolvedBuffer as c, PublishSourceFileSystem as d, AtlasRasterCompositeInput as i, PublishFileSystem as l, atlas as n, AtlasRasterMetadata as o, AtlasRasterBackend as r, AtlasRasterPipeline as s, AtlasOptions as t, PublishOutputFileSystem as u };