@imgly/codesign-mcp 0.1.0

package/dist/engine/asset-sources.js

@@ -0,0 +1,75 @@
+// packages/codesign-mcp/src/engine/asset-sources.ts
+//
+// Registers CE.SDK's default + demo asset sources on the headless engine so
+// `asset_search` has content to discover. Manifest roots default to the
+// IMG.LY CDN and are overridable via IMGLY_DEFAULT_ASSETS_BASE_URL /
+// IMGLY_DEMO_ASSETS_BASE_URL for self-hosted deployments. Idempotent:
+// skips when the demo image source is already present — ensureHeadlessEngine
+// is a process singleton, and the HTTP transport calls this once per session.
+// Best-effort: a CDN failure logs to stderr and leaves the engine usable.
+// Note: retries after total failure may re-add assets to already-populated
+// default sources (CE.SDK guards duplicate source ids, not duplicate assets);
+// partial failures after ly.img.image has landed are NOT retried.
+// `ly.img.text`'s manifest is not published on the CDN root (404), and the
+// SDK loads all manifests with Promise.all — one 404 rejects the whole call
+// and leaves WHICH sources registered up to fetch timing. Excluding it makes
+// registration deterministic.
+const MISSING_DEFAULT_SOURCES = ['ly.img.text'];
+/** Registered by addDemoAssetSources — its presence means we already ran. */
+const SENTINEL_SOURCE = 'ly.img.image';
+// Concurrent callers (HTTP createSession) share one in-flight registration —
+// the engine is a process singleton, so the guard lives at module level.
+let inFlight;
+export function ensureEngineAssetSources(engine) {
+    inFlight ??= registerOnce(engine);
+    return inFlight;
+}
+// Manifest roots for the JSON-defined asset sources. The @cesdk/node npm
+// package only bundles the WASM core (no manifests), so without an explicit
+// baseURL both calls resolve against the engine's file:// baseURL and fail.
+// The IMG.LY CDN is the fallback; deployments that self-host their asset
+// manifests override via env. These URLs are server configuration only —
+// agents never see them and must always go through engine.asset/asset_search.
+function defaultAssetsBaseUrl() {
+    return (process.env.IMGLY_DEFAULT_ASSETS_BASE_URL ?? 'https://cdn.img.ly/assets/v3');
+}
+function demoAssetsBaseUrl() {
+    return (process.env.IMGLY_DEMO_ASSETS_BASE_URL ??
+        'https://cdn.img.ly/assets/demo/v3');
+}
+function logSourceFailure(label, err) {
+    process.stderr.write(`codesign-mcp: ${label} failed (asset_search will see fewer sources): ${err instanceof Error ? err.message : String(err)}\n`);
+}
+async function registerOnce(engine) {
+    if (engine.asset.findAllSources().includes(SENTINEL_SOURCE))
+        return;
+    // Each call is independent so a failure in one doesn't block the other.
+    let anyFailed = false;
+    try {
+        await engine.addDefaultAssetSources({
+            baseURL: defaultAssetsBaseUrl(),
+            excludeAssetSourceIds: MISSING_DEFAULT_SOURCES
+        });
+    }
+    catch (err) {
+        logSourceFailure('addDefaultAssetSources', err);
+        anyFailed = true;
+    }
+    try {
+        await engine.addDemoAssetSources({ baseURL: demoAssetsBaseUrl() });
+    }
+    catch (err) {
+        logSourceFailure('addDemoAssetSources', err);
+        anyFailed = true;
+    }
+    // If the sentinel source still isn't present after both attempts, clear
+    // the guard so the next call can retry.
+    if (anyFailed && !engine.asset.findAllSources().includes(SENTINEL_SOURCE)) {
+        inFlight = undefined;
+    }
+}
+/** @internal test-only — resets the module-level in-flight guard. */
+export function resetEngineAssetSourcesForTest() {
+    inFlight = undefined;
+}
+//# sourceMappingURL=asset-sources.js.map

package/dist/engine/asset-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-sources.js","sourceRoot":"","sources":["../../src/engine/asset-sources.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,4EAA4E;AAC5E,wEAAwE;AACxE,qEAAqE;AACrE,sEAAsE;AACtE,6EAA6E;AAC7E,8EAA8E;AAC9E,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,kEAAkE;AAYlE,2EAA2E;AAC3E,4EAA4E;AAC5E,6EAA6E;AAC7E,8BAA8B;AAC9B,MAAM,uBAAuB,GAAG,CAAC,aAAa,CAAC,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,eAAe,GAAG,cAAc,CAAC;AAEvC,6EAA6E;AAC7E,yEAAyE;AACzE,IAAI,QAAmC,CAAC;AAExC,MAAM,UAAU,wBAAwB,CACtC,MAAyB;IAEzB,QAAQ,KAAK,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,yEAAyE;AACzE,yEAAyE;AACzE,8EAA8E;AAC9E,SAAS,oBAAoB;IAC3B,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,8BAA8B,CAC5E,CAAC;AACJ,CAAC;AACD,SAAS,iBAAiB;IACxB,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,0BAA0B;QACtC,mCAAmC,CACpC,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,GAAY;IACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iBAAiB,KAAK,kDACpB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,IAAI,CACL,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,MAAyB;IACnD,IAAI,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;QAAE,OAAO;IAEpE,wEAAwE;IACxE,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,sBAAsB,CAAC;YAClC,OAAO,EAAE,oBAAoB,EAAE;YAC/B,qBAAqB,EAAE,uBAAuB;SAC/C,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gBAAgB,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC;QAChD,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,mBAAmB,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,CAAC,CAAC;IACrE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,gBAAgB,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;QAC7C,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,wEAAwE;IACxE,wCAAwC;IACxC,IAAI,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC1E,QAAQ,GAAG,SAAS,CAAC;IACvB,CAAC;AACH,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,8BAA8B;IAC5C,QAAQ,GAAG,SAAS,CAAC;AACvB,CAAC","sourcesContent":["// packages/codesign-mcp/src/engine/asset-sources.ts\n//\n// Registers CE.SDK's default + demo asset sources on the headless engine so\n// `asset_search` has content to discover. Manifest roots default to the\n// IMG.LY CDN and are overridable via IMGLY_DEFAULT_ASSETS_BASE_URL /\n// IMGLY_DEMO_ASSETS_BASE_URL for self-hosted deployments. Idempotent:\n// skips when the demo image source is already present — ensureHeadlessEngine\n// is a process singleton, and the HTTP transport calls this once per session.\n// Best-effort: a CDN failure logs to stderr and leaves the engine usable.\n// Note: retries after total failure may re-add assets to already-populated\n// default sources (CE.SDK guards duplicate source ids, not duplicate assets);\n// partial failures after ly.img.image has landed are NOT retried.\n\n/** The slice of CreativeEngine this module needs — keeps it testable. */\nexport interface AssetSourceEngine {\n  asset: { findAllSources(): string[] };\n  addDefaultAssetSources(opts?: {\n    baseURL?: string;\n    excludeAssetSourceIds?: string[];\n  }): Promise<void>;\n  addDemoAssetSources(opts?: { baseURL?: string }): Promise<void>;\n}\n\n// `ly.img.text`'s manifest is not published on the CDN root (404), and the\n// SDK loads all manifests with Promise.all — one 404 rejects the whole call\n// and leaves WHICH sources registered up to fetch timing. Excluding it makes\n// registration deterministic.\nconst MISSING_DEFAULT_SOURCES = ['ly.img.text'];\n\n/** Registered by addDemoAssetSources — its presence means we already ran. */\nconst SENTINEL_SOURCE = 'ly.img.image';\n\n// Concurrent callers (HTTP createSession) share one in-flight registration —\n// the engine is a process singleton, so the guard lives at module level.\nlet inFlight: Promise<void> | undefined;\n\nexport function ensureEngineAssetSources(\n  engine: AssetSourceEngine\n): Promise<void> {\n  inFlight ??= registerOnce(engine);\n  return inFlight;\n}\n\n// Manifest roots for the JSON-defined asset sources. The @cesdk/node npm\n// package only bundles the WASM core (no manifests), so without an explicit\n// baseURL both calls resolve against the engine's file:// baseURL and fail.\n// The IMG.LY CDN is the fallback; deployments that self-host their asset\n// manifests override via env. These URLs are server configuration only —\n// agents never see them and must always go through engine.asset/asset_search.\nfunction defaultAssetsBaseUrl(): string {\n  return (\n    process.env.IMGLY_DEFAULT_ASSETS_BASE_URL ?? 'https://cdn.img.ly/assets/v3'\n  );\n}\nfunction demoAssetsBaseUrl(): string {\n  return (\n    process.env.IMGLY_DEMO_ASSETS_BASE_URL ??\n    'https://cdn.img.ly/assets/demo/v3'\n  );\n}\n\nfunction logSourceFailure(label: string, err: unknown): void {\n  process.stderr.write(\n    `codesign-mcp: ${label} failed (asset_search will see fewer sources): ${\n      err instanceof Error ? err.message : String(err)\n    }\\n`\n  );\n}\n\nasync function registerOnce(engine: AssetSourceEngine): Promise<void> {\n  if (engine.asset.findAllSources().includes(SENTINEL_SOURCE)) return;\n\n  // Each call is independent so a failure in one doesn't block the other.\n  let anyFailed = false;\n  try {\n    await engine.addDefaultAssetSources({\n      baseURL: defaultAssetsBaseUrl(),\n      excludeAssetSourceIds: MISSING_DEFAULT_SOURCES\n    });\n  } catch (err) {\n    logSourceFailure('addDefaultAssetSources', err);\n    anyFailed = true;\n  }\n  try {\n    await engine.addDemoAssetSources({ baseURL: demoAssetsBaseUrl() });\n  } catch (err) {\n    logSourceFailure('addDemoAssetSources', err);\n    anyFailed = true;\n  }\n\n  // If the sentinel source still isn't present after both attempts, clear\n  // the guard so the next call can retry.\n  if (anyFailed && !engine.asset.findAllSources().includes(SENTINEL_SOURCE)) {\n    inFlight = undefined;\n  }\n}\n\n/** @internal test-only — resets the module-level in-flight guard. */\nexport function resetEngineAssetSourcesForTest(): void {\n  inFlight = undefined;\n}\n"]}

package/dist/engine/cesdk-adapter.d.ts

@@ -0,0 +1,10 @@
+import type CreativeEngine from '@cesdk/engine';
+import type { EngineAdapter } from './session.js';
+/**
+ * Adapts a `@cesdk/engine` CreativeEngine instance to the EngineSession's
+ * generic EngineAdapter shape. One-to-one mapping; the only quirk is `reset`
+ * (CE.SDK has no `reset()` — we wipe by creating a new scene via the same
+ * patched create path `ensureHeadlessEngine` installed for the design-unit fix).
+ */
+export declare function cesdkAdapter(engine: CreativeEngine): EngineAdapter<CreativeEngine>;
+//# sourceMappingURL=cesdk-adapter.d.ts.map

package/dist/engine/cesdk-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cesdk-adapter.d.ts","sourceRoot":"","sources":["../../src/engine/cesdk-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,cAAc,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,cAAc,GACrB,aAAa,CAAC,cAAc,CAAC,CAW/B"}

package/dist/engine/cesdk-adapter.js

@@ -0,0 +1,19 @@
+/**
+ * Adapts a `@cesdk/engine` CreativeEngine instance to the EngineSession's
+ * generic EngineAdapter shape. One-to-one mapping; the only quirk is `reset`
+ * (CE.SDK has no `reset()` — we wipe by creating a new scene via the same
+ * patched create path `ensureHeadlessEngine` installed for the design-unit fix).
+ */
+export function cesdkAdapter(engine) {
+    return {
+        create: () => engine, // single-engine adapter: always the same instance
+        reset: async (eng) => {
+            eng.scene.create(); // wipes the active scene; design-unit patch from tools/engine.ts re-applies
+        },
+        loadFromString: async (eng, scene) => {
+            await eng.scene.loadFromString(scene);
+        },
+        saveToString: async (eng) => eng.scene.saveToString()
+    };
+}
+//# sourceMappingURL=cesdk-adapter.js.map

package/dist/engine/cesdk-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cesdk-adapter.js","sourceRoot":"","sources":["../../src/engine/cesdk-adapter.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAsB;IAEtB,OAAO;QACL,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,kDAAkD;QACxE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACnB,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,4EAA4E;QAClG,CAAC;QACD,cAAc,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;YACnC,MAAM,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACxC,CAAC;QACD,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE;KACtD,CAAC;AACJ,CAAC","sourcesContent":["import type CreativeEngine from '@cesdk/engine';\nimport type { EngineAdapter } from './session.js';\n\n/**\n * Adapts a `@cesdk/engine` CreativeEngine instance to the EngineSession's\n * generic EngineAdapter shape. One-to-one mapping; the only quirk is `reset`\n * (CE.SDK has no `reset()` — we wipe by creating a new scene via the same\n * patched create path `ensureHeadlessEngine` installed for the design-unit fix).\n */\nexport function cesdkAdapter(\n  engine: CreativeEngine\n): EngineAdapter<CreativeEngine> {\n  return {\n    create: () => engine, // single-engine adapter: always the same instance\n    reset: async (eng) => {\n      eng.scene.create(); // wipes the active scene; design-unit patch from tools/engine.ts re-applies\n    },\n    loadFromString: async (eng, scene) => {\n      await eng.scene.loadFromString(scene);\n    },\n    saveToString: async (eng) => eng.scene.saveToString()\n  };\n}\n"]}

package/dist/engine/index.d.ts

@@ -0,0 +1,3 @@
+export { cesdkAdapter } from './cesdk-adapter.js';
+export { type EngineAdapter, EngineSession, type EngineSessionOptions, type EngineSlot } from './session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,KAAK,aAAa,EAClB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC"}

package/dist/engine/index.js

@@ -0,0 +1,3 @@
+export { cesdkAdapter } from './cesdk-adapter.js';
+export { EngineSession } from './session.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAEL,aAAa,EAGd,MAAM,cAAc,CAAC","sourcesContent":["export { cesdkAdapter } from './cesdk-adapter.js';\nexport {\n  type EngineAdapter,\n  EngineSession,\n  type EngineSessionOptions,\n  type EngineSlot\n} from './session.js';\n"]}

package/dist/engine/mutex.d.ts

@@ -0,0 +1,5 @@
+export declare class Mutex {
+    private tail;
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=mutex.d.ts.map

package/dist/engine/mutex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../src/engine/mutex.ts"],"names":[],"mappings":"AAoBA,qBAAa,KAAK;IAIhB,OAAO,CAAC,IAAI,CAAuC;IAEnD,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAgBlD"}

package/dist/engine/mutex.js

@@ -0,0 +1,42 @@
+// A minimal FIFO async mutex.
+//
+// Why this exists: JavaScript is single-threaded, so plain variables never
+// suffer data races — but `await` is a yield point. Any code holding a
+// reference to shared mutable state across an `await` can be interrupted by
+// another in-flight async task that mutates the same state. Our CE.SDK engine
+// is exactly such shared state: the `edit` / `preview` / `export` tools
+// `loadFromString` a revision into the engine, run code against it, then
+// `saveToString` — a sequence of awaits. Two overlapping sessions sharing one
+// engine would interleave at those awaits and serialize the wrong scene.
+//
+// This mutex serializes such critical sections: each `runExclusive(fn)` runs
+// only after every previously-enqueued section has settled, so the engine is
+// loaded → mutated → saved by exactly one caller at a time. There is no timer
+// and no busy-waiting — it is pure promise chaining, so a waiting caller costs
+// nothing but a microtask.
+//
+// Not reentrant: calling runExclusive() from inside a section already holding
+// this mutex would wait for itself and deadlock. Our critical sections never
+// re-enter, so this is fine — but don't nest them.
+export class Mutex {
+    constructor() {
+        // The tail of the queue. Resolves once the most-recently-enqueued section
+        // has settled. Starts already-resolved so the very first caller runs on the
+        // next microtask with no extra wait.
+        this.tail = Promise.resolve();
+    }
+    runExclusive(fn) {
+        // Chain our section after whatever is queued. We attach `fn` as BOTH the
+        // fulfilment and rejection handler of the tail so our section runs no
+        // matter how the previous one settled — one throwing section must not
+        // wedge the queue. (`fn` ignores the settle value it is handed.)
+        const result = this.tail.then(fn, fn);
+        // The next caller waits for OUR section to settle. We park a result-
+        // swallowing continuation as the new tail so (a) the next section proceeds
+        // on either outcome and (b) this internal chain never raises an unhandled
+        // rejection. The real value/rejection still propagates through `result`.
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+//# sourceMappingURL=mutex.js.map

package/dist/engine/mutex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../src/engine/mutex.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,EAAE;AACF,2EAA2E;AAC3E,uEAAuE;AACvE,4EAA4E;AAC5E,8EAA8E;AAC9E,wEAAwE;AACxE,yEAAyE;AACzE,8EAA8E;AAC9E,yEAAyE;AACzE,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAC9E,+EAA+E;AAC/E,2BAA2B;AAC3B,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,mDAAmD;AACnD,MAAM,OAAO,KAAK;IAAlB;QACE,0EAA0E;QAC1E,4EAA4E;QAC5E,qCAAqC;QAC7B,SAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAkBrD,CAAC;IAhBC,YAAY,CAAI,EAAoB;QAClC,yEAAyE;QACzE,sEAAsE;QACtE,sEAAsE;QACtE,iEAAiE;QACjE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACtC,qEAAqE;QACrE,2EAA2E;QAC3E,0EAA0E;QAC1E,yEAAyE;QACzE,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CACrB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF","sourcesContent":["// A minimal FIFO async mutex.\n//\n// Why this exists: JavaScript is single-threaded, so plain variables never\n// suffer data races — but `await` is a yield point. Any code holding a\n// reference to shared mutable state across an `await` can be interrupted by\n// another in-flight async task that mutates the same state. Our CE.SDK engine\n// is exactly such shared state: the `edit` / `preview` / `export` tools\n// `loadFromString` a revision into the engine, run code against it, then\n// `saveToString` — a sequence of awaits. Two overlapping sessions sharing one\n// engine would interleave at those awaits and serialize the wrong scene.\n//\n// This mutex serializes such critical sections: each `runExclusive(fn)` runs\n// only after every previously-enqueued section has settled, so the engine is\n// loaded → mutated → saved by exactly one caller at a time. There is no timer\n// and no busy-waiting — it is pure promise chaining, so a waiting caller costs\n// nothing but a microtask.\n//\n// Not reentrant: calling runExclusive() from inside a section already holding\n// this mutex would wait for itself and deadlock. Our critical sections never\n// re-enter, so this is fine — but don't nest them.\nexport class Mutex {\n  // The tail of the queue. Resolves once the most-recently-enqueued section\n  // has settled. Starts already-resolved so the very first caller runs on the\n  // next microtask with no extra wait.\n  private tail: Promise<unknown> = Promise.resolve();\n\n  runExclusive<T>(fn: () => Promise<T>): Promise<T> {\n    // Chain our section after whatever is queued. We attach `fn` as BOTH the\n    // fulfilment and rejection handler of the tail so our section runs no\n    // matter how the previous one settled — one throwing section must not\n    // wedge the queue. (`fn` ignores the settle value it is handed.)\n    const result = this.tail.then(fn, fn);\n    // The next caller waits for OUR section to settle. We park a result-\n    // swallowing continuation as the new tail so (a) the next section proceeds\n    // on either outcome and (b) this internal chain never raises an unhandled\n    // rejection. The real value/rejection still propagates through `result`.\n    this.tail = result.then(\n      () => undefined,\n      () => undefined\n    );\n    return result;\n  }\n}\n"]}

package/dist/engine/session.d.ts

@@ -0,0 +1,50 @@
+export interface EngineAdapter<E = unknown> {
+    /** Construct (or check out from a pool) an engine instance. */
+    create(): E | Promise<E>;
+    /** Reset the engine to an empty scene (used when parent === null). */
+    reset(engine: E): Promise<void>;
+    /** Load a scene snapshot into the engine. */
+    loadFromString(engine: E, sceneBytes: string): Promise<void>;
+    /** Serialize the engine's current scene to a string. */
+    saveToString(engine: E): Promise<string>;
+}
+export interface EngineSlot<E = unknown> {
+    engine: E;
+    currentRevision: string | null;
+}
+export interface EngineSessionOptions<E = unknown> {
+    size: number;
+    adapter: EngineAdapter<E>;
+}
+export declare class EngineSession<E = unknown> {
+    private readonly opts;
+    private readonly slots;
+    private readonly stagedScenes;
+    constructor(opts: EngineSessionOptions<E>);
+    /**
+     * Pre-stage a scene snapshot so `acquire(rev)` can load it without going
+     * to the workspace. Used by RevisionStore-backed flows: the caller reads
+     * the .scene from the workspace once, then calls populate so subsequent
+     * acquire() calls in the same edit don't re-read.
+     *
+     * NOTE: This is an internal contract between EngineSession and the edit
+     * tool's load-then-acquire flow. Phase 2 may replace it with a direct
+     * `acquire(rev, sceneLoader)` callback.
+     */
+    populate(revision: string, sceneBytes: string): Promise<void>;
+    /** Drop a staged scene (call after acquire consumed it). */
+    private consumeStaged;
+    acquire(parent: string | null): Promise<EngineSlot<E>>;
+    commit(slot: EngineSlot<E>, newRevision: string): void;
+    markDirty(slot: EngineSlot<E>): void;
+    /**
+     * Return the first warm slot (currentRevision !== null) without any side
+     * effects, or undefined if no slot is currently warm. Used by tools that
+     * want to read the engine's current state (e.g. `preview` without a revision)
+     * without triggering a reset.
+     */
+    currentSlot(): EngineSlot<E> | undefined;
+    get size(): number;
+    private pickSlot;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/engine/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/engine/session.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,+DAA+D;IAC/D,MAAM,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,sEAAsE;IACtE,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,6CAA6C;IAC7C,cAAc,CAAC,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,wDAAwD;IACxD,YAAY,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,MAAM,EAAE,CAAC,CAAC;IACV,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;CAC3B;AAED,qBAAa,aAAa,CAAC,CAAC,GAAG,OAAO;IAIxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;gBAE7B,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAE1D;;;;;;;;;OASG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE,4DAA4D;IAC5D,OAAO,CAAC,aAAa;IAMf,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAwB5D,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAItD,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAIpC;;;;;OAKG;IACH,WAAW,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS;IAIxC,IAAI,IAAI,IAAI,MAAM,CAEjB;YAEa,QAAQ;CAcvB"}

package/dist/engine/session.js

@@ -0,0 +1,95 @@
+// EngineSession — owns N {engine, currentRevision} slots and the §4.7
+// contract that the engine state matches a requested `parent` before edit
+// code runs. Production wires it as size=1 (single CE.SDK engine via
+// cesdkAdapter); the multi-slot scaffolding is kept for a future Hosted
+// pool but is dormant today.
+//
+// What "session" means here: a long-lived engine context that tracks which
+// revision it is currently positioned at. Linear edits cost zero reloads
+// (sticky routing in pickSlot); markDirty invalidates the slot so the next
+// acquire pays a reload.
+//
+// The session is engine-agnostic: it talks to an EngineAdapter. Production
+// passes a CE.SDK adapter; tests pass a fake.
+export class EngineSession {
+    constructor(opts) {
+        this.opts = opts;
+        this.slots = [];
+        this.stagedScenes = new Map();
+    }
+    /**
+     * Pre-stage a scene snapshot so `acquire(rev)` can load it without going
+     * to the workspace. Used by RevisionStore-backed flows: the caller reads
+     * the .scene from the workspace once, then calls populate so subsequent
+     * acquire() calls in the same edit don't re-read.
+     *
+     * NOTE: This is an internal contract between EngineSession and the edit
+     * tool's load-then-acquire flow. Phase 2 may replace it with a direct
+     * `acquire(rev, sceneLoader)` callback.
+     */
+    async populate(revision, sceneBytes) {
+        this.stagedScenes.set(revision, sceneBytes);
+    }
+    /** Drop a staged scene (call after acquire consumed it). */
+    consumeStaged(revision) {
+        const scene = this.stagedScenes.get(revision);
+        this.stagedScenes.delete(revision);
+        return scene;
+    }
+    async acquire(parent) {
+        const slot = await this.pickSlot(parent);
+        if (slot.currentRevision === parent && parent !== null) {
+            // Linear edit on a warm slot — no reload, no reset.
+            return slot;
+        }
+        if (parent === null) {
+            await this.opts.adapter.reset(slot.engine);
+            slot.currentRevision = null;
+            return slot;
+        }
+        const staged = this.consumeStaged(parent);
+        if (staged === undefined) {
+            const err = new Error(`EngineSession.acquire: scene for revision "${parent}" was not staged. ` +
+                `The caller must populate(parent, sceneBytes) before acquire(parent) for non-null parents.`);
+            throw err;
+        }
+        await this.opts.adapter.loadFromString(slot.engine, staged);
+        slot.currentRevision = parent;
+        return slot;
+    }
+    commit(slot, newRevision) {
+        slot.currentRevision = newRevision;
+    }
+    markDirty(slot) {
+        slot.currentRevision = null;
+    }
+    /**
+     * Return the first warm slot (currentRevision !== null) without any side
+     * effects, or undefined if no slot is currently warm. Used by tools that
+     * want to read the engine's current state (e.g. `preview` without a revision)
+     * without triggering a reset.
+     */
+    currentSlot() {
+        return this.slots.find((s) => s.currentRevision !== null);
+    }
+    get size() {
+        return this.slots.length;
+    }
+    async pickSlot(parent) {
+        // Sticky routing: prefer the slot whose currentRevision matches parent.
+        for (const s of this.slots)
+            if (s.currentRevision === parent)
+                return s;
+        // Otherwise pick the first free slot, or create a new one if under cap.
+        if (this.slots.length < this.opts.size) {
+            const engine = await this.opts.adapter.create();
+            const slot = { engine, currentRevision: null };
+            this.slots.push(slot);
+            return slot;
+        }
+        // Cap reached — pick a dirty slot first, else the oldest.
+        const dirty = this.slots.find((s) => s.currentRevision === null);
+        return dirty ?? this.slots[0];
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/engine/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/engine/session.ts"],"names":[],"mappings":"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","sourcesContent":["// EngineSession — owns N {engine, currentRevision} slots and the §4.7\n// contract that the engine state matches a requested `parent` before edit\n// code runs. Production wires it as size=1 (single CE.SDK engine via\n// cesdkAdapter); the multi-slot scaffolding is kept for a future Hosted\n// pool but is dormant today.\n//\n// What \"session\" means here: a long-lived engine context that tracks which\n// revision it is currently positioned at. Linear edits cost zero reloads\n// (sticky routing in pickSlot); markDirty invalidates the slot so the next\n// acquire pays a reload.\n//\n// The session is engine-agnostic: it talks to an EngineAdapter. Production\n// passes a CE.SDK adapter; tests pass a fake.\n\nexport interface EngineAdapter<E = unknown> {\n  /** Construct (or check out from a pool) an engine instance. */\n  create(): E | Promise<E>;\n  /** Reset the engine to an empty scene (used when parent === null). */\n  reset(engine: E): Promise<void>;\n  /** Load a scene snapshot into the engine. */\n  loadFromString(engine: E, sceneBytes: string): Promise<void>;\n  /** Serialize the engine's current scene to a string. */\n  saveToString(engine: E): Promise<string>;\n}\n\nexport interface EngineSlot<E = unknown> {\n  engine: E;\n  currentRevision: string | null;\n}\n\nexport interface EngineSessionOptions<E = unknown> {\n  size: number;\n  adapter: EngineAdapter<E>;\n}\n\nexport class EngineSession<E = unknown> {\n  private readonly slots: EngineSlot<E>[] = [];\n  private readonly stagedScenes = new Map<string, string>();\n\n  constructor(private readonly opts: EngineSessionOptions<E>) {}\n\n  /**\n   * Pre-stage a scene snapshot so `acquire(rev)` can load it without going\n   * to the workspace. Used by RevisionStore-backed flows: the caller reads\n   * the .scene from the workspace once, then calls populate so subsequent\n   * acquire() calls in the same edit don't re-read.\n   *\n   * NOTE: This is an internal contract between EngineSession and the edit\n   * tool's load-then-acquire flow. Phase 2 may replace it with a direct\n   * `acquire(rev, sceneLoader)` callback.\n   */\n  async populate(revision: string, sceneBytes: string): Promise<void> {\n    this.stagedScenes.set(revision, sceneBytes);\n  }\n\n  /** Drop a staged scene (call after acquire consumed it). */\n  private consumeStaged(revision: string): string | undefined {\n    const scene = this.stagedScenes.get(revision);\n    this.stagedScenes.delete(revision);\n    return scene;\n  }\n\n  async acquire(parent: string | null): Promise<EngineSlot<E>> {\n    const slot = await this.pickSlot(parent);\n    if (slot.currentRevision === parent && parent !== null) {\n      // Linear edit on a warm slot — no reload, no reset.\n      return slot;\n    }\n    if (parent === null) {\n      await this.opts.adapter.reset(slot.engine);\n      slot.currentRevision = null;\n      return slot;\n    }\n    const staged = this.consumeStaged(parent);\n    if (staged === undefined) {\n      const err = new Error(\n        `EngineSession.acquire: scene for revision \"${parent}\" was not staged. ` +\n          `The caller must populate(parent, sceneBytes) before acquire(parent) for non-null parents.`\n      );\n      throw err;\n    }\n    await this.opts.adapter.loadFromString(slot.engine, staged);\n    slot.currentRevision = parent;\n    return slot;\n  }\n\n  commit(slot: EngineSlot<E>, newRevision: string): void {\n    slot.currentRevision = newRevision;\n  }\n\n  markDirty(slot: EngineSlot<E>): void {\n    slot.currentRevision = null;\n  }\n\n  /**\n   * Return the first warm slot (currentRevision !== null) without any side\n   * effects, or undefined if no slot is currently warm. Used by tools that\n   * want to read the engine's current state (e.g. `preview` without a revision)\n   * without triggering a reset.\n   */\n  currentSlot(): EngineSlot<E> | undefined {\n    return this.slots.find((s) => s.currentRevision !== null);\n  }\n\n  get size(): number {\n    return this.slots.length;\n  }\n\n  private async pickSlot(parent: string | null): Promise<EngineSlot<E>> {\n    // Sticky routing: prefer the slot whose currentRevision matches parent.\n    for (const s of this.slots) if (s.currentRevision === parent) return s;\n    // Otherwise pick the first free slot, or create a new one if under cap.\n    if (this.slots.length < this.opts.size) {\n      const engine = await this.opts.adapter.create();\n      const slot: EngineSlot<E> = { engine, currentRevision: null };\n      this.slots.push(slot);\n      return slot;\n    }\n    // Cap reached — pick a dirty slot first, else the oldest.\n    const dirty = this.slots.find((s) => s.currentRevision === null);\n    return dirty ?? this.slots[0];\n  }\n}\n"]}

package/dist/engine/uri-resolver.d.ts

@@ -0,0 +1,14 @@
+import type { ViewerUrlBuilder } from '../viewer/url-builder.js';
+/** The minimal slice of CreativeEngine this module needs — keeps it testable. */
+export interface UriResolvableEngine {
+    editor: {
+        setURIResolver(resolver: (uri: string, defaultResolver: (uri: string) => string) => string): void;
+    };
+}
+/**
+ * Make the engine resolve `workspace://…` asset URIs to the `/r/` HTTP route.
+ * Scenes persist the durable `workspace://` form; this rewrites it to a live
+ * fetch URL at load time, so a design survives a process restart / rewind.
+ */
+export declare function registerWorkspaceUriResolver(engine: UriResolvableEngine, urlBuilder: ViewerUrlBuilder): void;
+//# sourceMappingURL=uri-resolver.d.ts.map

package/dist/engine/uri-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-resolver.d.ts","sourceRoot":"","sources":["../../src/engine/uri-resolver.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIjE,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE;QACN,cAAc,CACZ,QAAQ,EAAE,CACR,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,KACrC,MAAM,GACV,IAAI,CAAC;KACT,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,mBAAmB,EAC3B,UAAU,EAAE,gBAAgB,GAC3B,IAAI,CAMN"}

package/dist/engine/uri-resolver.js

@@ -0,0 +1,12 @@
+const WORKSPACE_URI_PREFIX = 'workspace://';
+/**
+ * Make the engine resolve `workspace://…` asset URIs to the `/r/` HTTP route.
+ * Scenes persist the durable `workspace://` form; this rewrites it to a live
+ * fetch URL at load time, so a design survives a process restart / rewind.
+ */
+export function registerWorkspaceUriResolver(engine, urlBuilder) {
+    engine.editor.setURIResolver((uri, defaultResolver) => uri.startsWith(WORKSPACE_URI_PREFIX)
+        ? urlBuilder.forResource(uri.slice(WORKSPACE_URI_PREFIX.length))
+        : defaultResolver(uri));
+}
+//# sourceMappingURL=uri-resolver.js.map

package/dist/engine/uri-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-resolver.js","sourceRoot":"","sources":["../../src/engine/uri-resolver.ts"],"names":[],"mappings":"AAOA,MAAM,oBAAoB,GAAG,cAAc,CAAC;AAc5C;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAA2B,EAC3B,UAA4B;IAE5B,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,EAAE,eAAe,EAAE,EAAE,CACpD,GAAG,CAAC,UAAU,CAAC,oBAAoB,CAAC;QAClC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAChE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CACzB,CAAC;AACJ,CAAC","sourcesContent":["//\n// Registers a CE.SDK URI resolver that rewrites `workspace://<relpath>` asset\n// URIs (stored durably in scenes) to the HTTP `/r/` URL the engine can fetch.\n// Everything else delegates to CE.SDK's default resolver. Used by the headless\n// node engine; the browser viewer mirrors this logic in viewer.js.\nimport type { ViewerUrlBuilder } from '../viewer/url-builder.js';\n\nconst WORKSPACE_URI_PREFIX = 'workspace://';\n\n/** The minimal slice of CreativeEngine this module needs — keeps it testable. */\nexport interface UriResolvableEngine {\n  editor: {\n    setURIResolver(\n      resolver: (\n        uri: string,\n        defaultResolver: (uri: string) => string\n      ) => string\n    ): void;\n  };\n}\n\n/**\n * Make the engine resolve `workspace://…` asset URIs to the `/r/` HTTP route.\n * Scenes persist the durable `workspace://` form; this rewrites it to a live\n * fetch URL at load time, so a design survives a process restart / rewind.\n */\nexport function registerWorkspaceUriResolver(\n  engine: UriResolvableEngine,\n  urlBuilder: ViewerUrlBuilder\n): void {\n  engine.editor.setURIResolver((uri, defaultResolver) =>\n    uri.startsWith(WORKSPACE_URI_PREFIX)\n      ? urlBuilder.forResource(uri.slice(WORKSPACE_URI_PREFIX.length))\n      : defaultResolver(uri)\n  );\n}\n"]}

package/dist/frontmatter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Result of parsing a markdown file with optional YAML-ish frontmatter at the
+ * top. Only `name` and `description` keys are recognized; everything else in
+ * the fence block is ignored. Values are trimmed of surrounding whitespace.
+ *
+ * `body` is the input with any frontmatter fence stripped. When no fence is
+ * present, `body` equals the input verbatim.
+ */
+export interface ParsedFrontmatter {
+    name?: string;
+    description?: string;
+    body: string;
+}
+export declare function parseFrontmatter(input: string): ParsedFrontmatter;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAID,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAqCjE"}

package/dist/frontmatter.js

@@ -0,0 +1,46 @@
+const FENCE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+export function parseFrontmatter(input) {
+    const match = input.match(FENCE);
+    if (!match)
+        return { body: input };
+    const block = match[1];
+    const body = input.slice(match[0].length);
+    const out = { body };
+    const lines = block.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+        if (!m)
+            continue;
+        const [, key, rawValue] = m;
+        const trimmed = rawValue.trim();
+        // YAML pipe block scalar: `description: |` followed by indented lines.
+        // Treat the indented continuation as the value (joined with single
+        // spaces; the description field is logically a paragraph). Folded
+        // scalars (`>`) get the same treatment.
+        let value = trimmed;
+        if (trimmed === '|' || trimmed === '>') {
+            const collected = [];
+            let j = i + 1;
+            while (j < lines.length) {
+                const nextLine = lines[j];
+                if (nextLine === '' || /^\s+/.test(nextLine)) {
+                    if (nextLine.trim().length > 0)
+                        collected.push(nextLine.trim());
+                    j++;
+                }
+                else {
+                    break;
+                }
+            }
+            value = collected.join(' ').trim();
+            i = j - 1;
+        }
+        if (key === 'name')
+            out.name = value;
+        else if (key === 'description')
+            out.description = value;
+    }
+    return out;
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAcA,MAAM,KAAK,GAAG,mCAAmC,CAAC;AAElD,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAsB,EAAE,IAAI,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACtD,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,MAAM,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChC,uEAAuE;QACvE,mEAAmE;QACnE,kEAAkE;QAClE,wCAAwC;QACxC,IAAI,KAAK,GAAG,OAAO,CAAC;QACpB,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;YACvC,MAAM,SAAS,GAAa,EAAE,CAAC;YAC/B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;gBACxB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAC1B,IAAI,QAAQ,KAAK,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC7C,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;wBAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;oBAChE,CAAC,EAAE,CAAC;gBACN,CAAC;qBAAM,CAAC;oBACN,MAAM;gBACR,CAAC;YACH,CAAC;YACD,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;YACnC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACZ,CAAC;QACD,IAAI,GAAG,KAAK,MAAM;YAAE,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC;aAChC,IAAI,GAAG,KAAK,aAAa;YAAE,GAAG,CAAC,WAAW,GAAG,KAAK,CAAC;IAC1D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * Result of parsing a markdown file with optional YAML-ish frontmatter at the\n * top. Only `name` and `description` keys are recognized; everything else in\n * the fence block is ignored. Values are trimmed of surrounding whitespace.\n *\n * `body` is the input with any frontmatter fence stripped. When no fence is\n * present, `body` equals the input verbatim.\n */\nexport interface ParsedFrontmatter {\n  name?: string;\n  description?: string;\n  body: string;\n}\n\nconst FENCE = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n?/;\n\nexport function parseFrontmatter(input: string): ParsedFrontmatter {\n  const match = input.match(FENCE);\n  if (!match) return { body: input };\n  const block = match[1];\n  const body = input.slice(match[0].length);\n  const out: ParsedFrontmatter = { body };\n  const lines = block.split(/\\r?\\n/);\n  for (let i = 0; i < lines.length; i++) {\n    const line = lines[i];\n    const m = line.match(/^([A-Za-z0-9_-]+)\\s*:\\s*(.*)$/);\n    if (!m) continue;\n    const [, key, rawValue] = m;\n    const trimmed = rawValue.trim();\n    // YAML pipe block scalar: `description: |` followed by indented lines.\n    // Treat the indented continuation as the value (joined with single\n    // spaces; the description field is logically a paragraph). Folded\n    // scalars (`>`) get the same treatment.\n    let value = trimmed;\n    if (trimmed === '|' || trimmed === '>') {\n      const collected: string[] = [];\n      let j = i + 1;\n      while (j < lines.length) {\n        const nextLine = lines[j];\n        if (nextLine === '' || /^\\s+/.test(nextLine)) {\n          if (nextLine.trim().length > 0) collected.push(nextLine.trim());\n          j++;\n        } else {\n          break;\n        }\n      }\n      value = collected.join(' ').trim();\n      i = j - 1;\n    }\n    if (key === 'name') out.name = value;\n    else if (key === 'description') out.description = value;\n  }\n  return out;\n}\n"]}

package/dist/gateway/hosted-stub.d.ts

@@ -0,0 +1,6 @@
+import type { GatewayClient, GenerateImageInput, GenerateImageOutput } from './types.js';
+export declare class HostedStubGatewayClient implements GatewayClient {
+    readonly available = false;
+    generateImage(_input: GenerateImageInput): Promise<GenerateImageOutput>;
+}
+//# sourceMappingURL=hosted-stub.d.ts.map

package/dist/gateway/hosted-stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-stub.d.ts","sourceRoot":"","sources":["../../src/gateway/hosted-stub.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,qBAAa,uBAAwB,YAAW,aAAa;IAG3D,QAAQ,CAAC,SAAS,SAAS;IAErB,aAAa,CACjB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,mBAAmB,CAAC;CAKhC"}

package/dist/gateway/hosted-stub.js

@@ -0,0 +1,11 @@
+export class HostedStubGatewayClient {
+    constructor() {
+        // Phase 2 wiring is not implemented yet, so the hosted gateway can't
+        // fulfil requests — keep `asset_generate` hidden until it can.
+        this.available = false;
+    }
+    async generateImage(_input) {
+        throw new Error('HostedStubGatewayClient.generateImage: Phase 2 wires Clerk-bound gateway calls (not implemented)');
+    }
+}
+//# sourceMappingURL=hosted-stub.js.map

package/dist/gateway/hosted-stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-stub.js","sourceRoot":"","sources":["../../src/gateway/hosted-stub.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,uBAAuB;IAApC;QACE,qEAAqE;QACrE,+DAA+D;QACtD,cAAS,GAAG,KAAK,CAAC;IAS7B,CAAC;IAPC,KAAK,CAAC,aAAa,CACjB,MAA0B;QAE1B,MAAM,IAAI,KAAK,CACb,kGAAkG,CACnG,CAAC;IACJ,CAAC;CACF","sourcesContent":["import type {\n  GatewayClient,\n  GenerateImageInput,\n  GenerateImageOutput\n} from './types.js';\n\nexport class HostedStubGatewayClient implements GatewayClient {\n  // Phase 2 wiring is not implemented yet, so the hosted gateway can't\n  // fulfil requests — keep `asset_generate` hidden until it can.\n  readonly available = false;\n\n  async generateImage(\n    _input: GenerateImageInput\n  ): Promise<GenerateImageOutput> {\n    throw new Error(\n      'HostedStubGatewayClient.generateImage: Phase 2 wires Clerk-bound gateway calls (not implemented)'\n    );\n  }\n}\n"]}

package/dist/gateway/index.d.ts

@@ -0,0 +1,4 @@
+export { HostedStubGatewayClient } from './hosted-stub.js';
+export { LocalGatewayClient } from './local.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/gateway/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,cAAc,YAAY,CAAC"}

package/dist/gateway/index.js

@@ -0,0 +1,4 @@
+export { HostedStubGatewayClient } from './hosted-stub.js';
+export { LocalGatewayClient } from './local.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/gateway/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,cAAc,YAAY,CAAC","sourcesContent":["export { HostedStubGatewayClient } from './hosted-stub.js';\nexport { LocalGatewayClient } from './local.js';\nexport * from './types.js';\n"]}

package/dist/gateway/local.d.ts

@@ -0,0 +1,14 @@
+import { type GatewayClient, type GenerateImageInput, type GenerateImageOutput } from './types.js';
+export interface LocalGatewayClientOptions {
+    apiKey: string | undefined;
+    endpoint?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare class LocalGatewayClient implements GatewayClient {
+    private readonly opts;
+    constructor(opts: LocalGatewayClientOptions);
+    /** Available only when an `API_KEY` was provided. */
+    get available(): boolean;
+    generateImage(input: GenerateImageInput): Promise<GenerateImageOutput>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/gateway/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/gateway/local.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAElB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,qBAAa,kBAAmB,YAAW,aAAa;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,yBAAyB;IAE5D,qDAAqD;IACrD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAEK,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAmC7E"}

package/dist/gateway/local.js

@@ -0,0 +1,41 @@
+import { GatewayDisabledError } from './types.js';
+const DEFAULT_ENDPOINT = 'https://gateway.img.ly/v1/images/generate';
+export class LocalGatewayClient {
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Available only when an `API_KEY` was provided. */
+    get available() {
+        return Boolean(this.opts.apiKey);
+    }
+    async generateImage(input) {
+        if (!this.opts.apiKey) {
+            throw new GatewayDisabledError('asset generation is disabled: set `API_KEY` (your IMG.LY gateway key) to enable. See `handbook` → `asset_generate`.');
+        }
+        const f = this.opts.fetch ?? globalThis.fetch;
+        const res = await f(this.opts.endpoint ?? DEFAULT_ENDPOINT, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.opts.apiKey}`,
+                'content-type': 'application/json'
+            },
+            body: JSON.stringify({
+                prompt: input.prompt,
+                width: input.width,
+                height: input.height
+            })
+        });
+        if (!res.ok) {
+            throw new Error(`asset_generate: gateway returned ${res.status} ${res.statusText}`);
+        }
+        const ct = res.headers.get('content-type') ?? 'image/png';
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        const mimeType = (ct.startsWith('image/jpeg')
+            ? 'image/jpeg'
+            : ct.startsWith('image/webp')
+                ? 'image/webp'
+                : 'image/png');
+        return { bytes, mimeType };
+    }
+}
+//# sourceMappingURL=local.js.map