@pygmalionjs/pygmalion 0.10.0 → 0.11.1

package/dist-lib/testing.js

@@ -1,5 +1,5 @@
-import { bW as l, T as u } from "./runtime-BOfDlGPR.js";
-import { bi as y, cc as b, cd as E, ce as P, be as T, as as $ } from "./runtime-BOfDlGPR.js";
+import { bW as l, T as u } from "./runtime-Bxn8116i.js";
+import { bi as y, cc as b, cd as E, ce as P, be as T, as as $ } from "./runtime-Bxn8116i.js";
 const v = {
   mirror: ["status", "refresh", "refs"],
   session: ["open", "check", "previewVisual", "applyVisual", "revertVisual"],

package/dist-lib/types/document/contracts.d.ts

@@ -158,6 +158,16 @@ export interface ResolvedDocumentNode {
 }
 /** Optional presentation-time instance resolution; normal editing uses canonical definitions. */
 export interface DocumentResolveOptions {
+    /**
+     * Expand a source occurrence before resolving its component subtree. The
+     * continuation retains inherited overrides and cycle checks, skips this
+     * occurrence's expansion hook, and accepts callback overrides for its subtree.
+     * A definition root is resolved through its instance, not expanded separately.
+     */
+    expandNode?: (input: {
+        node: DocumentNode;
+        instancePath: readonly string[];
+    }, resolve: (options?: DocumentResolveOptions) => ResolvedDocumentNode) => readonly ResolvedDocumentNode[];
     resolveInstance?: (input: {
         node: DocumentNode;
         /** Outer-to-inner instance IDs. IDs remain opaque, including slashes. */

package/dist-lib/types/document/prototype.d.ts

@@ -8,6 +8,8 @@
  * side effects a player must perform; time enters only through `now`.
  */
 import type { DesignDocument, DocumentDiagnostic, DocumentDuplicateMetadataRemapper, DocumentNode, DocumentResolveOptions, DocumentTransaction, ResolvedDocumentNode } from './contracts.js';
+import type { PrototypeOccurrence, PrototypeRowPath } from './prototypeOccurrence.js';
+export type { PrototypeOccurrence, PrototypeRowPath } from './prototypeOccurrence.js';
 export declare const PROTOTYPE_METADATA_KEY = "prototype";
 export declare const PROTOTYPE_INTERACTIONS_PROPERTY = "interactions";
 /** Upper bound for an authored transition in this player. */
@@ -252,14 +254,28 @@ export interface PrototypeSceneLayer {
     fill: string | null;
     node: DocumentNode;
     depth: number;
+    occurrence?: PrototypeOccurrence;
+}
+export interface PrototypeResolvedSceneNode extends Omit<ResolvedDocumentNode, 'children'> {
+    rowPath: PrototypeRowPath;
+    instancePath?: readonly string[];
+    children: PrototypeResolvedSceneNode[];
+}
+/** Supplies the same expanded scene used by the rendering surface, without owning authoring data. */
+export interface PrototypeRuntimeContext {
+    resolveScene(document: DesignDocument, state: PrototypeState, rootId: string, sceneId: string): PrototypeResolvedSceneNode;
 }
 /** Stable occurrence key. Every ID is opaque; nested instances never share canonical state. */
-export declare function prototypeVariantKey(instancePath: readonly string[]): string;
+export declare function prototypeVariantKey(instancePath: readonly string[], occurrence?: PrototypeOccurrence): string;
 /** Presentation-only variant resolution; neither the document nor shared definitions are changed. */
-export declare function prototypeResolveOptions(document: DesignDocument, variants: Readonly<Record<string, string>>): DocumentResolveOptions;
+export declare function prototypeResolveOptions(document: DesignDocument, variants: Readonly<Record<string, string>>, occurrence?: PrototypeOccurrence): DocumentResolveOptions;
 /** Resolves runtime variants explicitly; invalid choices never silently render canonical state. */
 export declare function resolvePrototypeScene(document: DesignDocument, rootId: string, variants?: Readonly<Record<string, string>>): ResolvedDocumentNode;
-export declare function prototypeSceneLayers(document: DesignDocument, rootId: string, variants?: Readonly<Record<string, string>>): PrototypeSceneLayer[];
+export declare function prototypeSceneLayers(document: DesignDocument, rootId: string, variants?: Readonly<Record<string, string>>, options?: {
+    state: PrototypeState;
+    sceneId?: string;
+    context?: PrototypeRuntimeContext;
+}): PrototypeSceneLayer[];
 export interface PrototypeSmartAnimatePair {
     name: string;
     from: PrototypeSceneLayer;
@@ -301,6 +317,7 @@ export type PrototypeRevert = {
 export interface PrototypeHold {
     nodeId: string;
     trigger: 'hover' | 'press';
+    occurrence?: PrototypeOccurrence;
     /** Screen-space bounds of the hotspot when the hold began; a surface keeps it hit-testable across navigation. */
     bounds: {
         sceneId: string;
@@ -327,7 +344,7 @@ export interface PrototypeState {
     history: string[];
     overlays: PrototypeOverlayState[];
     variables: Record<string, PrototypeValue>;
-    /** Runtime variant choices keyed by prototypeVariantKey(outer-to-inner instance path). */
+    /** Runtime variant choices keyed by the authored instance path and optional scene/row occurrence. */
     variants: Record<string, string>;
     scroll: Record<string, {
         x: number;
@@ -338,6 +355,7 @@ export interface PrototypeState {
         targetId: string;
         transition: PrototypeTransition;
         at: number;
+        occurrence?: PrototypeOccurrence;
     } | null;
     timers: PrototypeTimer[];
     holds: PrototypeHold[];
@@ -352,6 +370,7 @@ export type PrototypeEvent =
 {
     type: PrototypePointerEventType;
     path: readonly string[];
+    occurrence?: PrototypeOccurrence;
 } | {
     type: 'key';
     key: string;
@@ -397,6 +416,7 @@ export type PrototypeEffect = {
     sceneId: string;
     targetId: string;
     transition: PrototypeTransition;
+    occurrence?: PrototypeOccurrence;
 } | {
     type: 'open-url';
     url: string;
@@ -415,10 +435,11 @@ export interface PrototypeStartOptions {
     flowId?: string | null;
     startingNodeId?: string;
     now?: number;
+    context?: PrototypeRuntimeContext;
 }
 /** The initial state of a flow (or of an explicit starting screen); delay triggers on the screen are armed. */
 export declare function createPrototypeState(document: DesignDocument, options?: PrototypeStartOptions): PrototypeState;
 /** The earliest moment the state changes without input, or null when it is at rest. */
 export declare function prototypeNextDeadline(state: PrototypeState): number | null;
 /** One pure step: the event (or the passage of time) against a frozen document; time is `now`. */
-export declare function stepPrototype(document: DesignDocument, previous: PrototypeState, event: PrototypeEvent, now: number): PrototypeStepResult;
+export declare function stepPrototype(document: DesignDocument, previous: PrototypeState, event: PrototypeEvent, now: number, runtime?: PrototypeRuntimeContext): PrototypeStepResult;

package/dist-lib/types/document/prototypeOccurrence.d.ts

@@ -0,0 +1,18 @@
+/** A stable row address, ordered from the outer repeat to the inner repeat. */
+export type PrototypeRowPath = readonly {
+    repeatId: string;
+    key: string | number;
+}[];
+/** A rendered occurrence. Overlay scene IDs distinguish separate openings of one screen. */
+export interface PrototypeOccurrence {
+    sceneId: string;
+    rowPath: PrototypeRowPath;
+}
+export declare function prototypeOccurrenceValid(value: unknown): value is PrototypeOccurrence;
+export declare function prototypeRowPathPrefix(prefix: PrototypeRowPath, path: PrototypeRowPath): boolean;
+export declare function prototypeOccurrenceEqual(left: PrototypeOccurrence | undefined, right: PrototypeOccurrence | undefined): boolean;
+export declare function encodePrototypeVariantKey(instancePath: readonly string[], occurrence?: PrototypeOccurrence): string;
+export declare function decodePrototypeVariantKey(key: string): {
+    instancePath: string[];
+    occurrence?: PrototypeOccurrence;
+} | null;

package/dist-lib/types/lib.d.ts

@@ -424,3 +424,5 @@ export { PrototypePanel } from './workspace/edit/PrototypePanel.js';
 export { PrototypePlayer } from './workspace/view/PrototypePlayer.js';
 export type { PrototypePlayerProps } from './workspace/view/PrototypePlayer.js';
 export * from './workspace/view/prototypePlayback.js';
+export { createPrototypeProjectionContext } from './workspace/edit/prototypeProjection.js';
+export type { PrototypeProjectionContext } from './workspace/edit/prototypeProjection.js';

package/dist-lib/types/workspace/edit/clipboard.d.ts

@@ -22,7 +22,7 @@ export interface PasteDesignResult {
     nodeIds: Record<string, string>;
 }
 /** Pure paste plan; commit the returned same-identity snapshot as one undoable transaction. */
-export declare function pasteDesignSubtrees(target: DesignDocument, payload: DesignClipboard, options: {
+export declare function pasteDesignSubtrees(targetInput: DesignDocument, payloadInput: DesignClipboard, options: {
     parentId: string;
     allocateId: (sourceId: string) => string;
     offset?: {

package/dist-lib/types/workspace/edit/projection.d.ts

@@ -9,4 +9,4 @@ export interface ProjectedDocumentNode {
     children: ProjectedDocumentNode[];
 }
 /** Fixture rows affect this disposable scene only, never canonical document geometry. */
-export declare function projectDocumentScene(document: DesignDocument, data: DataProjection | null, resolveOptions?: DocumentResolveOptions): ProjectedDocumentNode;
+export declare function projectDocumentScene(document: DesignDocument, data: DataProjection | null, resolveOptions?: DocumentResolveOptions, resolveRowOptions?: (rowPath: BindingRuntimeScope['rowPath']) => DocumentResolveOptions): ProjectedDocumentNode;

package/dist-lib/types/workspace/edit/prototypeProjection.d.ts

@@ -0,0 +1,7 @@
+import type { DataProjection } from '../../binding/preview.js';
+import type { PrototypeRuntimeContext } from '../../document/prototype.js';
+export interface PrototypeProjectionContext extends PrototypeRuntimeContext {
+    readonly projection: DataProjection | null;
+}
+/** One captured data projection supplies runtime hit testing, layout and presentation rendering. */
+export declare function createPrototypeProjectionContext(data: DataProjection | null): PrototypeProjectionContext;

package/dist-lib/types/workspace/view/PrototypePlayer.d.ts

@@ -1,16 +1,17 @@
 import type { ReactNode } from 'react';
 import type { DesignDocument } from '../../document/contracts.js';
-import { type PrototypeState } from '../../document/prototype.js';
+import { type PrototypeRuntimeContext, type PrototypeState } from '../../document/prototype.js';
 import { type PrototypeClock } from './prototypePlayback.js';
 
 export interface PrototypePlayerProps {
     document: DesignDocument;
     /** Uses the same document/component renderer as Edit, with authoring controls disabled. */
-    renderScene(rootId: string, state: PrototypeState): ReactNode;
-    sceneSize?(rootId: string, state: PrototypeState): {
+    renderScene(rootId: string, state: PrototypeState, sceneId?: string): ReactNode;
+    sceneSize?(rootId: string, state: PrototypeState, sceneId?: string): {
         width: number;
         height: number;
     } | undefined;
+    context?: PrototypeRuntimeContext;
     onClose(): void;
     clock?: PrototypeClock;
 }

package/dist-lib/types/workspace/view/prototypePlayback.d.ts

@@ -1,5 +1,5 @@
 import type { DesignDocument, DocumentNode, ResolvedDocumentNode } from '../../document/contracts.js';
-import { type PrototypeEffect, type PrototypeEvent, type PrototypeStartOptions, type PrototypeState } from '../../document/prototype.js';
+import { type PrototypeEffect, type PrototypeEvent, type PrototypeRuntimeContext, type PrototypeStartOptions, type PrototypeState } from '../../document/prototype.js';
 export interface PrototypeClock {
     now(): number;
     schedule(callback: () => void, delayMs: number): unknown;
@@ -38,7 +38,7 @@ export interface PrototypePresentationScene {
         opacity: number;
     } | null;
 }
-export declare function prototypeScene(document: DesignDocument, state: PrototypeState): PrototypePresentationScene[];
+export declare function prototypeScene(document: DesignDocument, state: PrototypeState, context?: PrototypeRuntimeContext): PrototypePresentationScene[];
 export declare function prototypeFlowOptions(document: DesignDocument): {
     id: string;
     label: string;

package/jsx-source-reconciler.d.ts

@@ -8,6 +8,9 @@ export interface ReconcileSourceProjection { anchors: JsxStructureAnchor[]; node
 export interface JsxSourceReconcilerOptions {
   file: string;
   identityFile: string;
+  /** Additional nullable inputs, captured at construction. Each requires an own input key and proof on both sides.
+   * Names must be unique, nonblank, and different from file. identityFile is always included and may appear once. Default: []. */
+  optionalInputFiles?: readonly string[];
   rootId: string;
   definitionId: string;
   screenId: string;

package/node/jsx-source-reconciler.mjs

@@ -19,7 +19,7 @@ const sourceLayout = layout => layout ? { direction: layout.direction, gap: layo
 export function createJsxSourceReconciler({
   file, identityFile, rootId, definitionId, screenId, documentId, opaqueNodeIds,
   projectSource, resolveWrapper = () => undefined, compileDocumentSource,
-  allowUnchangedIslandRelocation = false,
+  allowUnchangedIslandRelocation = false, optionalInputFiles = [],
 }) {
   if ([file, identityFile, rootId, definitionId, screenId, documentId].some(value => typeof value !== 'string' || !value)
     || file === identityFile || !Array.isArray(opaqueNodeIds) || new Set(opaqueNodeIds).size !== opaqueNodeIds.length
@@ -27,13 +27,19 @@ export function createJsxSourceReconciler({
     || ![projectSource, resolveWrapper, compileDocumentSource].every(value => typeof value === 'function')) {
     throw new TypeError('A source reconciler requires explicit files, node identities, and projection/compiler callbacks.');
   }
+  const optionalInputs = Array.isArray(optionalInputFiles) ? [...optionalInputFiles] : null;
+  if (!optionalInputs || new Set(optionalInputs).size !== optionalInputs.length
+    || optionalInputs.some(value => typeof value !== 'string' || !value.trim() || value === file)) {
+    throw new TypeError('Optional source inputs must be unique nonempty file names excluding the main source file.');
+  }
+  const nullableInputs = new Set([identityFile, ...optionalInputs]);
   opaqueNodeIds = [...opaqueNodeIds];
   function capturedInputs(value) {
-    if (!record(value) || Object.keys(value).length > 500 || !Object.hasOwn(value, identityFile)
-      || typeof value[file] !== 'string' || !value[file]) fail('inputs-invalid', 'Complete source and identity inputs are required.');
+    if (!record(value) || Object.keys(value).length > 500 || [...nullableInputs].some(inputFile => !Object.hasOwn(value, inputFile))
+      || typeof value[file] !== 'string' || !value[file]) fail('inputs-invalid', 'Complete source, identity, and declared optional inputs are required.');
     let size = 0;
     for (const [inputFile, content] of Object.entries(value)) {
-      if (content === null && inputFile === identityFile) continue;
+      if (content === null && nullableInputs.has(inputFile)) continue;
       if (typeof content !== 'string' || Buffer.from(content).toString('utf8') !== content) fail('inputs-invalid', 'Source inputs must be UTF-8 strings.', inputFile);
       size += Buffer.byteLength(content);
     }
@@ -92,7 +98,9 @@ export function createJsxSourceReconciler({
       }
       seen.add(proof.file);
     }
-    if (!seen.has(file) || !seen.has(identityFile)) fail('proofs-invalid', 'Source and identity proofs are both required.');
+    if (!seen.has(file) || [...nullableInputs].some(inputFile => !seen.has(inputFile))) {
+      fail('proofs-invalid', 'Source, identity, and declared optional input proofs are required.');
+    }
   }
   function verifyProjection(document, projection) {
     for (const node of projection.nodes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "Apache-2.0",
   "repository": {