@pygmalionjs/pygmalion 0.8.1 → 0.10.0

package/source-module.d.ts

@@ -0,0 +1,16 @@
+export interface SourceModuleBuildResult {
+  outputFiles?: readonly { text: string }[];
+}
+
+export interface BundledSourceModuleOptions {
+  /** A trusted bundler supplied by the consuming build tool. */
+  build(options: Record<string, unknown>): Promise<SourceModuleBuildResult>;
+  /** Application aliases, plugins, dependency paths, loaders, and entry declaration. */
+  buildOptions: Record<string, unknown>;
+  /** Absolute logical filename used by CommonJS resolution; no output file is written. */
+  filename: string;
+  require?: (id: string) => unknown;
+}
+
+/** Executes trusted source code in the current process. This is not an execution sandbox. */
+export declare function evaluateBundledSourceModule<T = unknown>(options: BundledSourceModuleOptions): Promise<T>;

package/source-responsive.d.ts

@@ -0,0 +1,10 @@
+import type { InspectApplyPayload } from './dist-lib/types/editor/inspect.js';
+import type { SourceFilePlan } from './dist-lib/types/host/sourceFilePlan.js';
+import type { ResponsiveLayoutDocument, ResponsiveLayoutRange, ResponsiveLayoutSourceTarget, WorkspaceResponsiveSourceMapping } from './dist-lib/types/workspace/source/responsiveContracts.js';
+export interface ResponsiveSourceInputFile { file: string; source: string; sha256: string }
+export declare function readResponsiveLayoutSource(input: { files: readonly ResponsiveSourceInputFile[]; ranges: readonly ResponsiveLayoutRange[]; targets: readonly ResponsiveLayoutSourceTarget[] }): ResponsiveLayoutDocument;
+export declare function compileResponsiveSourcePlan(input: {
+  appRoot: string; sourceRevision: string; mapping: WorkspaceResponsiveSourceMapping;
+  before: ResponsiveLayoutDocument; after: ResponsiveLayoutDocument;
+  additionalStyles?: InspectApplyPayload['styles']; signal?: AbortSignal;
+}): Promise<SourceFilePlan>;

package/source-service.d.ts

@@ -0,0 +1,92 @@
+import type { Plugin, ViteDevServer } from 'vite';
+import type { DesignDocument } from './dist-lib/types/document/contracts.js';
+import type { SourceFilePlan } from './dist-lib/types/host/sourceFilePlan.js';
+import type { InspectApplyResult, InspectPreviewResult } from './dist-lib/types/editor/host.js';
+import type { WorkspaceTarget } from './dist-lib/types/workspace/contracts.js';
+import type { WorkspaceFileSourceRequest, WorkspaceSourceBaseline, WorkspaceSourceReconcileInput, WorkspaceSourceReconcileResult } from './dist-lib/types/workspace/source/flowContracts.js';
+import type { WorkspaceTokenLibraryBaseline, WorkspaceTokenSourceRequest } from './dist-lib/types/workspace/tokens/contracts.js';
+import type { TokenLibraryDocument } from './dist-lib/types/token-library/contracts.js';
+import type { SourceFilePlanOptions } from './source-files.js';
+import type { WorkspaceSourcePlanService } from './workspace-source-plan.js';
+
+export type SourceInputs = Readonly<Record<string, string | null>>;
+export type SourceArchive = <T>(sourceRevision: string, signal: AbortSignal,
+  operation: (context: { appRoot: string; sourceRevision?: string; signal?: AbortSignal }) => Promise<T>) => Promise<T>;
+export interface SourceInputOptions { optionalFiles?: readonly string[]; signal?: AbortSignal; maxBytes?: number }
+export declare function assertSourceInputParent(root: string, file: string): Promise<void>;
+export declare function readSourceInputs(appRoot: string, files: readonly string[], options?: SourceInputOptions): Promise<Record<string, string | null>>;
+export declare function readProvenSourceFiles(appRoot: string, proofs: SourceFilePlan['proofs'], options?: SourceInputOptions): Promise<Map<string, { file: string; sha256: string | null; source: string | null }>>;
+export declare function withSourceFiles<T>(options: { files: Map<string, string>; signal?: AbortSignal }, operation: (root: string) => Promise<T>): Promise<T>;
+
+interface SourceWriters {
+  previewPlan?(root: string, plan: SourceFilePlan, options: SourceFilePlanOptions): Promise<Pick<InspectPreviewResult, 'files' | 'affectedFiles'>>;
+  applyPlan?(root: string, plan: SourceFilePlan, options: SourceFilePlanOptions): Promise<{ applied: number }>;
+}
+export interface WorkspaceSourceSessionOptions<Codec, Projection = unknown, Identity = unknown> extends SourceWriters {
+  appRoot: string;
+  allowedFiles: readonly string[];
+  overlayFiles?: readonly string[];
+  optionalFiles?: readonly string[];
+  inputFiles(codec: Codec): readonly string[];
+  loadCodec(): Promise<Codec>;
+  assertTarget(target: WorkspaceTarget, signal: AbortSignal): void | Promise<void>;
+  archive: SourceArchive;
+  currentRevision(): Promise<string>;
+  projectBaseline(input: { codec: Codec; target: WorkspaceTarget; sourceInputs: SourceInputs; projectedStructure?: Projection }, signal: AbortSignal): Promise<WorkspaceSourceBaseline>;
+  compilePlan(input: { appRoot: string; sourceRevision: string; before: DesignDocument; after: DesignDocument; mapping: WorkspaceSourceBaseline['mapping']; signal: AbortSignal; reconciledIdentity?: Identity }): Promise<SourceFilePlan>;
+  reconcile(input: WorkspaceSourceReconcileInput & {
+    baselineInputs: SourceInputs; externalInputs: SourceInputs; baselineIdentity?: Identity;
+    loadBaseline(input: { target: WorkspaceTarget; sourceInputs: SourceInputs; projectedStructure?: Projection }, signal: AbortSignal): Promise<WorkspaceSourceBaseline>;
+  }, signal: AbortSignal): Promise<WorkspaceSourceReconcileResult>;
+  projectReconcileInputs(input: { baselineInputs: SourceInputs; externalInputs: SourceInputs; baselineIdentity?: Identity }): { projectedStructure: Projection; identity: Identity };
+  applyMessage?: string;
+}
+export interface WorkspaceSourceSession extends WorkspaceSourcePlanService {
+  reconcile(input: WorkspaceSourceReconcileInput, signal?: AbortSignal): Promise<WorkspaceSourceReconcileResult>;
+  /** Validates the retained review before overlaying reconciled bytes into an isolated root. */
+  preparePreviewSource(input: WorkspaceFileSourceRequest, root: string, signal?: AbortSignal): Promise<void>;
+}
+export declare function createWorkspaceSourceSession<Codec, Projection = unknown, Identity = unknown>(options: WorkspaceSourceSessionOptions<Codec, Projection, Identity>): WorkspaceSourceSession;
+
+export interface LoadedTokenSource<SourceFiles = unknown, Ledger = unknown> extends WorkspaceTokenLibraryBaseline {
+  sourceFiles: SourceFiles;
+  ledger: Ledger;
+  consumerFiles: readonly string[];
+}
+export interface TokenSourceServiceOptions<Codec, SourceFiles = unknown, Ledger = unknown> extends SourceWriters {
+  appRoot: string;
+  loadCodec(): Promise<Codec>;
+  assertRevision(sourceRevision: string, signal?: AbortSignal): void | Promise<void>;
+  assertTarget(target: WorkspaceTarget, signal: AbortSignal): void | Promise<void>;
+  archive: SourceArchive;
+  loadSource(input: { appRoot: string; sourceRevision: string; codec: Codec; signal: AbortSignal }): Promise<LoadedTokenSource<SourceFiles, Ledger>>;
+  compilePlan(input: { appRoot: string; sourceRevision: string; before: TokenLibraryDocument; after: TokenLibraryDocument; codec: Codec; signal: AbortSignal; dependenciesReady: true }): Promise<SourceFilePlan>;
+  listConsumers(appRoot: string, signal: AbortSignal): Promise<readonly string[]>;
+  currentRevision(): Promise<string>;
+  regenerate(signal: AbortSignal): Promise<unknown>;
+  install(root: string, signal: AbortSignal): Promise<unknown>;
+  applyMessage?: string;
+  regenerationFailureMessage?(error: unknown): string;
+}
+export interface TokenSourceService<SourceFiles = unknown, Ledger = unknown> {
+  load(sourceRevision: string, signal?: AbortSignal): Promise<WorkspaceTokenLibraryBaseline & { sourceFiles: SourceFiles; ledger: Ledger }>;
+  compile(input: { baseline: WorkspaceTokenLibraryBaseline; document: TokenLibraryDocument }, signal?: AbortSignal): Promise<SourceFilePlan>;
+  preview(request: WorkspaceTokenSourceRequest, signal?: AbortSignal): Promise<InspectPreviewResult>;
+  validatePreviewRequest(request: WorkspaceTokenSourceRequest, signal?: AbortSignal): Promise<WorkspaceTokenSourceRequest>;
+  apply(request: WorkspaceTokenSourceRequest, signal?: AbortSignal): Promise<InspectApplyResult>;
+  dispose(): void;
+}
+export declare function createTokenSourceService<Codec, SourceFiles = unknown, Ledger = unknown>(options: TokenSourceServiceOptions<Codec, SourceFiles, Ledger>): TokenSourceService<SourceFiles, Ledger>;
+
+export declare function sourceServicePlugin<Service extends { dispose(): void | Promise<void> }>(options: {
+  name?: string;
+  endpoint: string;
+  operations: readonly (keyof Service & string)[];
+  createService(server: ViteDevServer): Service;
+  transformInput?(operation: keyof Service & string, input: unknown): unknown;
+  maxBytes?: number;
+}): {
+  plugin: Plugin;
+  validatePreviewRequest: Service extends { validatePreviewRequest: infer Method } ? Method : never;
+  preparePreviewSource: Service extends { preparePreviewSource: infer Method } ? Method : never;
+};

package/source-structure.d.ts

@@ -0,0 +1,155 @@
+import type { SourceFilePlan } from './dist-lib/types/host/sourceFilePlan.js';
+import type { WorkspaceStructureGroupLayout, WorkspaceStructureWrapperDeclaration } from './dist-lib/types/workspace/source/contracts.js';
+
+export interface JsxStructureAnchor { nodeId: string; file: string; start: number; end: number; expected: string }
+export type JsxStructureGroupLayout = WorkspaceStructureGroupLayout;
+/**
+ * Host declaration for element wrappers. A group with a layout compiles to
+ * `<tagName className={styleAlias.<derived class>}>` plus one managed block in the
+ * stylesheet; spacing pairs document pixel values with the host's exact CSS spellings.
+ */
+export type JsxStructureWrapperContract = WorkspaceStructureWrapperDeclaration;
+/** The contract and the complete stylesheet bytes matching the JSX source being read. */
+export interface JsxStructureWrapperEvidence { contract: JsxStructureWrapperContract; source: string }
+export type JsxStructureOperation =
+  | { kind: 'reorder'; parentId: string; children: readonly string[] }
+  /** Index addresses the final list after removing the node from its original parent. */
+  | { kind: 'reparent'; nodeId: string; parentId: string; index: number }
+  /** A layout requires the plan's wrapper contract; without one the group is an anonymous fragment. */
+  | { kind: 'group'; nodeIds: readonly string[]; groupId: string; layout?: JsxStructureGroupLayout }
+  /** Removes an anonymous fragment or a generated wrapper element together with its managed block. */
+  | { kind: 'ungroup'; nodeId: string };
+export interface JsxStructureDiagnostic { code: string; message: string; file?: string; nodeId?: string }
+export interface JsxStructureSourceNode {
+  nodeId: string; parentId: string | null; children: string[];
+  kind: 'element' | 'expression' | 'fragment' | 'text';
+  tagName?: string;
+  /** Only a static string literal is reported; bindings and CSS module expressions are not evaluated. */
+  className?: string;
+  /** Present only for a generated wrapper element proved against its managed stylesheet block. */
+  layout?: JsxStructureGroupLayout;
+  wrapper?: { className: string };
+  runtimePath: number[]; start: number; end: number;
+}
+/** Persist alongside the source in the same reviewed file plan; offsets are UTF-16 source positions. */
+export interface JsxStructureIdentity {
+  version: 1;
+  file: string;
+  sourceSha256: string;
+  rootId: string;
+  opaqueNodeIds: string[];
+  anchors: { nodeId: string; start: number; end: number }[];
+  /** Generated wrapper groups; absent when the island has none. */
+  wrappers?: { nodeId: string; className: string }[];
+}
+/** Checks the supplied anchor snippets and full AST projection before returning serializable evidence. */
+export declare function createJsxStructureIdentity(input: {
+  file: string; source: string; rootId: string; anchors: readonly JsxStructureAnchor[]; opaqueNodeIds?: readonly string[];
+  /** Required to record wrapper groups; the stylesheet must be the bytes reviewed with this source. */
+  wrapper?: JsxStructureWrapperEvidence;
+}): JsxStructureIdentity;
+/**
+ * Throws on stale bytes, malformed identity, missing nodes or ambiguous ranges. Never guesses IDs.
+ * Recorded wrappers require the wrapper evidence; a wrapper whose element or managed block was
+ * edited by hand fails closed instead of degrading to a plain element.
+ */
+export declare function reimportJsxStructureSource(input: {
+  file: string; source: string; identity: JsxStructureIdentity; wrapper?: JsxStructureWrapperEvidence;
+}): { anchors: JsxStructureAnchor[]; nodes: JsxStructureSourceNode[] };
+/**
+ * Throws for invalid source, ambiguous roots, or opaque offsets outside the projected tree.
+ * Runtime paths exclude blank multiline indentation and comment-only expressions. Expressions
+ * that evaluate to false or undefined still occupy one slot; their values are never evaluated.
+ */
+export declare function inspectJsxStructureSource(input: {
+  file: string; source: string; rootStart: number; opaqueNodeStarts?: readonly number[];
+}): { anchors: JsxStructureAnchor[]; nodes: JsxStructureSourceNode[] };
+/**
+ * Pure source compilation; the host audits allowed containers and the complete canonical-document delta.
+ * Expressions move only as complete opaque chunks within one static JSX tree. Rendered text and
+ * standalone comments in an edited parent block ambiguous hierarchy changes. Groups without a layout
+ * are anonymous fragments, which do not provide a DOM box. With a wrapper contract, a group with a
+ * layout emits one intrinsic element and a managed block in the contract stylesheet, which must be
+ * supplied in `files` and allowed for writing. Neither form certifies preservation of component
+ * reconciliation state across a React remount. Props, handlers, and expression source are preserved
+ * without evaluation or fixture substitution.
+ */
+export declare function compileJsxStructurePlan(input: {
+  sourceRevision: string;
+  files: readonly { file: string; source: string; sha256: string }[];
+  anchors: readonly JsxStructureAnchor[];
+  operations: readonly JsxStructureOperation[];
+  allowedFiles: readonly string[];
+  excludedSourcePrefixes?: readonly string[];
+  wrapper?: JsxStructureWrapperContract;
+}): { status: 'ready'; payload: SourceFilePlan; anchors: JsxStructureAnchor[] }
+  | { status: 'unchanged'; anchors: JsxStructureAnchor[] }
+  | { status: 'blocked'; diagnostics: JsxStructureDiagnostic[] };
+
+export interface JsxStructureReconciliationInput {
+  file: string;
+  baseline: { sourceRevision: string; source: string; identity: JsxStructureIdentity };
+  external: {
+    /** May equal the baseline commit for explicitly checked working-copy changes. */
+    sourceRevision: string;
+    source: string;
+    sha256: string;
+    /**
+     * Complete host-supplied correspondence to the current AST. Retained IDs explicitly mean
+     * the same source-owned nodes; new IDs must be fresh. Core never infers this mapping from
+     * names, positions, snippets, runtime values, or example data. Every range and hash is checked.
+     */
+    identity: JsxStructureIdentity;
+  };
+  /** Complete audited draft structure relative to baseline; the host checks other document deltas. */
+  operations: readonly JsxStructureOperation[];
+  allowedFiles: readonly string[];
+  excludedSourcePrefixes?: readonly string[];
+  /** Required when either identity records wrapper groups or the draft adds one. */
+  wrapper?: {
+    contract: JsxStructureWrapperContract;
+    baselineSource: string;
+    externalSource: string;
+    externalSha256: string;
+  };
+}
+export interface JsxStructureReconciliationShape {
+  kind: JsxStructureSourceNode['kind'];
+  parentId: string | null;
+  children: string[];
+  layout: JsxStructureGroupLayout | null;
+}
+export interface JsxStructureReconciliationDiagnostic extends JsxStructureDiagnostic {
+  action: 'refresh-source' | 'map-identities' | 'resolve-overlap';
+  baseline?: JsxStructureReconciliationShape | null;
+  external?: JsxStructureReconciliationShape | null;
+  draft?: JsxStructureReconciliationShape | null;
+}
+export interface ReconciledJsxStructureSource {
+  file: string;
+  baselineSourceRevision: string;
+  baselineSourceSha256: string;
+  /** The external revision is retained; the baseline is never silently relabeled. */
+  sourceRevision: string;
+  externalSourceSha256: string;
+  source: string;
+  /** Persist with the resulting source using a separately reviewed, exact file plan. */
+  identity: JsxStructureIdentity;
+  /** The contract stylesheet after the merge; present only when wrapper input was supplied. */
+  stylesheetSource?: string;
+  anchors: JsxStructureAnchor[];
+  nodes: JsxStructureSourceNode[];
+  diagnostics: readonly [];
+}
+export type JsxStructureReconciliationResult =
+  | (ReconciledJsxStructureSource & { status: 'ready'; payload: SourceFilePlan })
+  | (ReconciledJsxStructureSource & { status: 'unchanged' })
+  | { status: 'conflict'; diagnostics: readonly JsxStructureReconciliationDiagnostic[] };
+/**
+ * Pure, explicit three-way reconciliation. Disjoint child-list changes merge; overlapping lists,
+ * removals, incompatible boundaries, competing wrapper layouts and ambiguous identities require
+ * explicit conflict resolution. External props and expression bytes survive structure-only edits.
+ * Host source ownership and document/binding validation still apply. A ready plan proves the
+ * latest external bytes only.
+ */
+export declare function reconcileJsxStructurePlan(input: JsxStructureReconciliationInput): JsxStructureReconciliationResult;

package/workspace-draft-entry.d.ts

@@ -0,0 +1,15 @@
+import type { WorkspaceDraftRecipe } from './dist-lib/types/workspace/source/draftRecipe.js';
+
+/** Trusted build-time declarations for the mounted application's browser entry. */
+export interface WorkspaceDraftEntryOptions {
+  documentRevision: string;
+  recipe: WorkspaceDraftRecipe;
+  /** Module resolving the SDK recipe runner. Defaults to the public package. */
+  sdkModule?: string;
+  /** An application module exporting its desired-state adapter. */
+  desiredStateAdapter?: { module: string; exportName: string };
+  failureMessage?: string;
+}
+
+/** Returns ESM source for a virtual build entry; the application supplies its own bundler and boot setup. */
+export declare function createWorkspaceDraftEntry(options: WorkspaceDraftEntryOptions): string;

package/workspace-source-plan.d.ts

@@ -0,0 +1,44 @@
+import type { DesignDocument } from './dist-lib/types/document/contracts.js';
+import type { SourceFilePlan } from './dist-lib/types/host/sourceFilePlan.js';
+import type { InspectApplyResult, InspectPreviewResult } from './dist-lib/types/editor/host.js';
+import type { WorkspaceTarget } from './dist-lib/types/workspace/contracts.js';
+import type { WorkspaceFileSourceRequest, WorkspaceSourceBaseline } from './dist-lib/types/workspace/source/flowContracts.js';
+
+export interface WorkspaceSourcePlanCompileInput {
+  target: WorkspaceTarget;
+  baseline: WorkspaceSourceBaseline;
+  document: DesignDocument;
+}
+
+export interface WorkspaceSourcePlanServiceOptions {
+  /** Callbacks receive detached, deeply frozen JSON captures and must settle on cancellation. */
+  loadBaseline(target: WorkspaceTarget, signal: AbortSignal): Promise<WorkspaceSourceBaseline>;
+  /** Owns full document validation and the source semantics of every changed field. */
+  compilePlan(input: WorkspaceSourcePlanCompileInput, signal: AbortSignal): Promise<SourceFilePlan>;
+  /** Must check current file proofs; the service checks complete, nonempty diff coverage. */
+  previewPlan(plan: SourceFilePlan, target: WorkspaceTarget, signal: AbortSignal): Promise<Pick<InspectPreviewResult, 'files' | 'affectedFiles'> & Partial<Pick<InspectPreviewResult, 'qa'>>>;
+  /** Must recheck current source revision and proofs and apply the complete plan atomically. */
+  applyPlan(plan: SourceFilePlan, target: WorkspaceTarget, signal: AbortSignal): Promise<InspectApplyResult>;
+  assertTarget(target: WorkspaceTarget, signal: AbortSignal): void | Promise<void>;
+  /** Default and maximum: 30 minutes. Review never extends this lifetime. */
+  receiptTtlMs?: number;
+  /** Default and maximum: 8 compiled document receipts. */
+  maxReceipts?: number;
+  now?: () => number;
+}
+
+export interface WorkspaceSourcePlanService {
+  /** Loads may run concurrently; every other operation is mutually exclusive. */
+  load(target: WorkspaceTarget, signal?: AbortSignal): Promise<WorkspaceSourceBaseline>;
+  /** Reloads and compares the complete baseline before issuing a bounded server receipt. */
+  compile(input: WorkspaceSourcePlanCompileInput, signal?: AbortSignal): Promise<SourceFilePlan>;
+  preview(request: WorkspaceFileSourceRequest, signal?: AbortSignal): Promise<InspectPreviewResult>;
+  /** A writer attempt consumes all receipts. Cancellation does not establish rollback. */
+  apply(request: WorkspaceFileSourceRequest, signal?: AbortSignal): Promise<InspectApplyResult>;
+  /** Required before preparing an immutable built artifact from a browser-supplied file plan. */
+  validatePreviewRequest(request: WorkspaceFileSourceRequest, signal?: AbortSignal): Promise<WorkspaceFileSourceRequest>;
+  /** Aborts in-flight callbacks, clears receipts, and rejects their later completions. */
+  dispose(): void;
+}
+
+export declare function createWorkspaceSourcePlanService(options: WorkspaceSourcePlanServiceOptions): WorkspaceSourcePlanService;