@ggui-ai/dev-stack 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@ggui-ai/dev-stack` — shared open dev engine for the ggui
+ * protocol. Every CLI / host that runs the local dev loop
+ * (`ggui dev` today, future `ggui dev --tunnel`, the local hub,
+ * any closed-CLI compat shim) consumes this barrel.
+ *
+ * Layering:
+ *
+ *   @ggui-ai/ui-registry        — contract (types-only)
+ *   @ggui-ai/project-config     — manifest schema / loaders
+ *   @ggui-ai/agent-runtime      — agent runtime adapter seam
+ *           │
+ *           ▼
+ *   @ggui-ai/dev-stack          — THIS PACKAGE: local engine
+ *           │
+ *           ▼
+ *   @ggui-ai/cli                — `ggui` binary; thin shell
+ *
+ * Design rule: the agent framework is never hardcoded — one engine
+ * composes under every host, with the runtime supplied via an
+ * adapter seam.
+ */
+export { LocalUiRegistry, type LocalUiRegistryOptions, type LocalBundleResult, type BundleErrorLocation, } from './local-registry/local-registry.js';
+export { discoverLocalUis, discoverFromGguiJsonPath, type DiscoveredUi, type DiscoveryIssue, type DiscoveryResult, type DiscoverOptions, } from '@ggui-ai/project-config/node';
+export { compileUiOnDemand, resolveEntryFile, COMPILED_BUNDLE_CONTENT_TYPE, type CompileResult, } from './local-registry/compile-ui.js';
+export { createLocalWatcher, statOrNull, type LocalWatcher, type LocalWatcherOptions, type WatchListener, } from './local-registry/watcher.js';
+export { startDevServer, type DevServerOptions, type DevServerHandle, } from './dev-server/http.js';
+export { openEventStream, type SseOptions } from './dev-server/events.js';
+export { renderHubHtml, serveHubShell, type HubShellContext, } from './dev-server/hub.js';
+export { renderHubPreviewHtml, serveHubPreviewShell, serveHubPreviewBundle, resolveHubPreviewBundlePath, extractSelectedId, type HubPreviewShellContext, } from './dev-server/hub-preview.js';
+export { createSecurityPolicy, type CreatePolicyOptions, type DevServerSecurityPolicy, type PolicyOutcome, } from './dev-server/auth.js';
+export { runDev, GguiDevError, DEFAULT_DEV_PORT, DEFAULT_DEV_HOST, type DevOptions, type DevBootstrap, } from './run-dev.js';
+export { RuntimeSupervisor, DEFAULT_RUNTIME_BUFFER_SIZE, emptyRuntimeSnapshot, formatRuntimeEventLine, type RuntimeSupervisorOptions, type RuntimeStateSnapshot, type EmptyRuntimeStateSnapshot, type AnyRuntimeStateSnapshot, type RuntimeEventRecord, } from './runtime-supervisor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,oCAAoC,CAAC;AAM5C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,4BAA4B,EAC5B,KAAK,aAAa,GACnB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAG1E,OAAO,EACL,aAAa,EACb,aAAa,EACb,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,2BAA2B,EAC3B,iBAAiB,EACjB,KAAK,sBAAsB,GAC5B,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,MAAM,EACN,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AAKtB,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,49 @@
+/**
+ * `@ggui-ai/dev-stack` — shared open dev engine for the ggui
+ * protocol. Every CLI / host that runs the local dev loop
+ * (`ggui dev` today, future `ggui dev --tunnel`, the local hub,
+ * any closed-CLI compat shim) consumes this barrel.
+ *
+ * Layering:
+ *
+ *   @ggui-ai/ui-registry        — contract (types-only)
+ *   @ggui-ai/project-config     — manifest schema / loaders
+ *   @ggui-ai/agent-runtime      — agent runtime adapter seam
+ *           │
+ *           ▼
+ *   @ggui-ai/dev-stack          — THIS PACKAGE: local engine
+ *           │
+ *           ▼
+ *   @ggui-ai/cli                — `ggui` binary; thin shell
+ *
+ * Design rule: the agent framework is never hardcoded — one engine
+ * composes under every host, with the runtime supplied via an
+ * adapter seam.
+ */
+// Local UI registry
+export { LocalUiRegistry, } from './local-registry/local-registry.js';
+// Discovery — re-export from @ggui-ai/project-config/node for
+// consumers that have historically imported these symbols from the
+// dev-stack barrel. The canonical home is the schema-owner package;
+// dev-stack's `LocalUiRegistry` consumes the same helper directly.
+export { discoverLocalUis, discoverFromGguiJsonPath, } from '@ggui-ai/project-config/node';
+// Compile-on-demand
+export { compileUiOnDemand, resolveEntryFile, COMPILED_BUNDLE_CONTENT_TYPE, } from './local-registry/compile-ui.js';
+// Watcher
+export { createLocalWatcher, statOrNull, } from './local-registry/watcher.js';
+// HTTP dev server
+export { startDevServer, } from './dev-server/http.js';
+// SSE event stream
+export { openEventStream } from './dev-server/events.js';
+// Local dev hub — HTML shell served from the same server at `/hub`.
+export { renderHubHtml, serveHubShell, } from './dev-server/hub.js';
+// Local dev hub — preview iframe shell served at `/hub/preview`.
+export { renderHubPreviewHtml, serveHubPreviewShell, serveHubPreviewBundle, resolveHubPreviewBundlePath, extractSelectedId, } from './dev-server/hub-preview.js';
+// Auth / CORS policy
+export { createSecurityPolicy, } from './dev-server/auth.js';
+// Orchestration — the seam every local-dev host composes against.
+export { runDev, GguiDevError, DEFAULT_DEV_PORT, DEFAULT_DEV_HOST, } from './run-dev.js';
+// Runtime supervision — ring-buffered view of the supervised agent
+// runtime, consumed by the CLI banner, the future hub, and the
+// HTTP `/runtime/...` snapshot surface.
+export { RuntimeSupervisor, DEFAULT_RUNTIME_BUFFER_SIZE, emptyRuntimeSnapshot, formatRuntimeEventLine, } from './runtime-supervisor.js';

package/dist/local-registry/compile-ui.d.ts

@@ -0,0 +1,67 @@
+import { type Message } from 'esbuild';
+import type { UiManifest } from '@ggui-ai/project-config';
+/** Content type the compiled bundle is served with. Matches the
+ * precompiled path for consistency. */
+export declare const COMPILED_BUNDLE_CONTENT_TYPE = "application/javascript+react";
+export interface CompileInputs {
+    /** Absolute project root — directory containing `ggui.json`. */
+    projectRoot: string;
+    /** Absolute path to the `ggui.ui.json` this compile is for. */
+    manifestPath: string;
+    /** Parsed manifest — `entryPoint` drives the compile target when present. */
+    manifest: UiManifest;
+}
+export interface CompileOk {
+    kind: 'ok';
+    /** Raw ESM code. */
+    code: string;
+    /** Absolute path compiled (the entry point). Useful for logs. */
+    entry: string;
+    /** esbuild info/warning messages, if any. */
+    warnings: Message[];
+}
+export interface CompileMissingEntry {
+    kind: 'missing-entry';
+    /**
+     * Which places were tried — absolute paths. Either the explicit
+     * `manifest.entryPoint` (single element) or the fallback filename
+     * candidates (in search order).
+     */
+    tried: string[];
+}
+export interface CompileFailure {
+    kind: 'failure';
+    entry: string;
+    errors: Message[];
+    warnings: Message[];
+}
+export type CompileResult = CompileOk | CompileMissingEntry | CompileFailure;
+/**
+ * Resolve the entry file for a UI manifest.
+ *
+ * Precedence:
+ *   1. `manifest.entryPoint` (relative to `projectRoot`, or
+ *      absolute). Single-candidate result.
+ *   2. Fallback: the {@link ENTRY_CANDIDATES} filenames beside the
+ *      manifest. First hit wins.
+ *
+ * Returns the resolved absolute path, or `null` with the list of
+ * candidates that were tried (for the 404/missing-entry response).
+ */
+export declare function resolveEntryFile(inputs: CompileInputs): {
+    entry: string;
+} | {
+    tried: string[];
+};
+/**
+ * Compile a UI's TSX source to an ESM bundle. Returns a discriminated
+ * result — consumers branch on `kind` to render the right HTTP
+ * response / log.
+ *
+ * esbuild's programmatic build can throw on catastrophic failures
+ * (e.g. native binary missing). Those bubble up to the caller — the
+ * HTTP layer surfaces them as 500s since they are environment /
+ * install problems, not user-source problems.
+ */
+export declare function compileUiOnDemand(inputs: CompileInputs): Promise<CompileResult>;
+//# sourceMappingURL=compile-ui.d.ts.map

package/dist/local-registry/compile-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-ui.d.ts","sourceRoot":"","sources":["../../src/local-registry/compile-ui.ts"],"names":[],"mappings":"AAoCA,OAAO,EAA4B,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AA6B1D;uCACuC;AACvC,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,EAAE,UAAU,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB;;;;OAIG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,mBAAmB,GAAG,cAAc,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAkB/F;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAqCrF"}

package/dist/local-registry/compile-ui.js

@@ -0,0 +1,148 @@
+/**
+ * Compile-on-demand for local `ggui dev` UIs.
+ *
+ * Resolves the authored TSX entry for a `ggui.ui.json` and runs
+ * esbuild against it, producing an ESM bundle Studio can hand to
+ * `DynamicComponent`. This replaces the "must pre-compile" state
+ * the foundation slice left behind — `ggui dev` now feels like a
+ * real dev server: start it, open Studio, see the render.
+ *
+ * Trust model:
+ *
+ *   The closed `core/src/validation/ui-compiler.ts` layers in
+ *   `validateComponentDetailed` — security patterns (`eval`,
+ *   `fetch`), import allowlist enforcement, size caps. Those exist
+ *   because the cloud pipeline accepts user-uploaded TSX and runs
+ *   it downstream. **Localhost `ggui dev` is NOT that pipeline.**
+ *   The developer is compiling their own project's source on their
+ *   own machine; a token-gated origin-allowlisted local server has
+ *   the same trust as the developer's shell. No security
+ *   validation here.
+ *
+ * Shape chosen for v1:
+ *
+ *   - esbuild `build` mode with bundle: true, so multi-file UIs
+ *     work (import sibling helpers, theme tokens, wire hooks).
+ *   - Sandbox externals match the runtime Studio renderer
+ *     (`DynamicComponent` in `@ggui-ai/react`). React, the design
+ *     system, `@ggui-ai/wire`, and `@ggui-ai/react` stay external
+ *     and resolve against the import map Studio provides at
+ *     render time.
+ *   - No caching. Every request recompiles. esbuild TSX transform
+ *     is ~50-200ms for a typical single-screen UI — fine for the
+ *     dev loop. A watcher-driven cache lands with HMR, not here.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { build } from 'esbuild';
+/**
+ * Packages the Studio runtime renderer already resolves from its
+ * own bundle (via `@ggui-ai/design/module-loader`'s import-map).
+ * Keeping them out of the compiled bundle keeps the artifact small
+ * and lets Studio's in-tree React instance be shared across every
+ * rendered UI.
+ */
+const SANDBOX_EXTERNALS = [
+    'react',
+    'react/*',
+    'react-dom',
+    'react-dom/*',
+    '@ggui-ai/design',
+    '@ggui-ai/design/*',
+    '@ggui-ai/wire',
+    '@ggui-ai/wire/*',
+    '@ggui-ai/react',
+    '@ggui-ai/react/*',
+];
+/**
+ * Filename candidates for the entry point when the manifest
+ * doesn't declare one. Kept narrow so the convention is predictable
+ * rather than "anything with a `.tsx` extension."
+ */
+const ENTRY_CANDIDATES = ['ggui.ui.tsx', 'index.tsx', 'component.tsx'];
+/** Content type the compiled bundle is served with. Matches the
+ * precompiled path for consistency. */
+export const COMPILED_BUNDLE_CONTENT_TYPE = 'application/javascript+react';
+/**
+ * Resolve the entry file for a UI manifest.
+ *
+ * Precedence:
+ *   1. `manifest.entryPoint` (relative to `projectRoot`, or
+ *      absolute). Single-candidate result.
+ *   2. Fallback: the {@link ENTRY_CANDIDATES} filenames beside the
+ *      manifest. First hit wins.
+ *
+ * Returns the resolved absolute path, or `null` with the list of
+ * candidates that were tried (for the 404/missing-entry response).
+ */
+export function resolveEntryFile(inputs) {
+    const { projectRoot, manifestPath, manifest } = inputs;
+    if (manifest.entryPoint && manifest.entryPoint.length > 0) {
+        const declared = isAbsolute(manifest.entryPoint)
+            ? manifest.entryPoint
+            : resolve(projectRoot, manifest.entryPoint);
+        return existsSync(declared) ? { entry: declared } : { tried: [declared] };
+    }
+    const manifestDir = dirname(manifestPath);
+    const tried = [];
+    for (const filename of ENTRY_CANDIDATES) {
+        const candidate = resolve(manifestDir, filename);
+        tried.push(candidate);
+        if (existsSync(candidate))
+            return { entry: candidate };
+    }
+    return { tried };
+}
+/**
+ * Compile a UI's TSX source to an ESM bundle. Returns a discriminated
+ * result — consumers branch on `kind` to render the right HTTP
+ * response / log.
+ *
+ * esbuild's programmatic build can throw on catastrophic failures
+ * (e.g. native binary missing). Those bubble up to the caller — the
+ * HTTP layer surfaces them as 500s since they are environment /
+ * install problems, not user-source problems.
+ */
+export async function compileUiOnDemand(inputs) {
+    const resolved = resolveEntryFile(inputs);
+    if ('tried' in resolved) {
+        return { kind: 'missing-entry', tried: resolved.tried };
+    }
+    const entry = resolved.entry;
+    try {
+        const result = await build({
+            entryPoints: [entry],
+            bundle: true,
+            format: 'esm',
+            target: 'es2020',
+            jsx: 'automatic',
+            jsxImportSource: 'react',
+            minify: false,
+            write: false,
+            external: SANDBOX_EXTERNALS,
+            platform: 'browser',
+            absWorkingDir: inputs.projectRoot,
+            treeShaking: true,
+            logLevel: 'silent',
+        });
+        const code = result.outputFiles[0]?.text ?? '';
+        return { kind: 'ok', code, entry, warnings: result.warnings };
+    }
+    catch (err) {
+        if (isBuildFailure(err)) {
+            return {
+                kind: 'failure',
+                entry,
+                errors: err.errors,
+                warnings: err.warnings,
+            };
+        }
+        throw err;
+    }
+}
+function isBuildFailure(err) {
+    return (err !== null &&
+        typeof err === 'object' &&
+        Array.isArray(err.errors) &&
+        Array.isArray(err.warnings));
+}

package/dist/local-registry/local-registry.d.ts

@@ -0,0 +1,93 @@
+import type { UiBundle, UiManifestEntry, UiRegistry, UiRegistryCapabilities } from '@ggui-ai/ui-registry';
+import { type DiscoveryIssue, type GguiJsonV1 } from '@ggui-ai/project-config/node';
+import { type WatchListener } from './watcher.js';
+export interface LocalUiRegistryOptions {
+    /** Absolute project root — directory containing `ggui.json`. */
+    projectRoot: string;
+    /** The parsed `ggui.json`. Only `blueprints.include` is consumed today. */
+    manifest: GguiJsonV1;
+}
+/**
+ * Richer bundle result — the HTTP layer branches on this to return
+ * the right status code / JSON body. `LocalUiRegistry.getBundle`
+ * collapses everything into `UiBundle | undefined` per the
+ * `@ggui-ai/ui-registry` contract.
+ */
+export type LocalBundleResult = {
+    kind: 'ok';
+    bundle: UiBundle;
+    source: 'precompiled' | 'compiled';
+} | {
+    kind: 'not-found';
+} | {
+    kind: 'missing-entry';
+    tried: string[];
+} | {
+    kind: 'compile-failed';
+    entry: string;
+    errors: Array<{
+        text: string;
+        location: BundleErrorLocation | null;
+    }>;
+    warnings: Array<{
+        text: string;
+        location: BundleErrorLocation | null;
+    }>;
+};
+/** Flat, wire-safe subset of esbuild's Location shape. */
+export interface BundleErrorLocation {
+    file: string;
+    line: number;
+    column: number;
+    length: number;
+    lineText: string;
+}
+export declare class LocalUiRegistry implements UiRegistry {
+    readonly capabilities: UiRegistryCapabilities;
+    private readonly projectRoot;
+    private readonly manifest;
+    private entriesById;
+    /** Absolute manifest dir → id. Rebuilt on every refresh so the
+     * watcher can attribute source-file changes to the right UI. */
+    private manifestDirIndex;
+    private lastIssues;
+    private loaded;
+    private watcher;
+    constructor(options: LocalUiRegistryOptions);
+    /**
+     * Force a re-scan of the filesystem against `blueprints.include`.
+     * Use after edits when `subscribe` isn't wired yet. The HTTP layer
+     * can call this on a PUT `/uis/refresh` or similar — not part of
+     * this slice.
+     */
+    refresh(): Promise<{
+        uiCount: number;
+        issues: DiscoveryIssue[];
+    }>;
+    /**
+     * Subscribe to registry change events. Flips
+     * `capabilities.observable` from spec to reality. Starts the
+     * underlying filesystem watcher on first call and keeps it
+     * alive until all listeners unsubscribe AND {@link close} is
+     * invoked (lifetime controlled by the enclosing dev server,
+     * not by subscriber churn — SSE clients come and go).
+     */
+    subscribe(listener: WatchListener): () => void;
+    /** Shut down the watcher (if any) and drop listeners. */
+    close(): Promise<void>;
+    private ensureWatcher;
+    /** Diagnostic snapshot — NOT part of the `UiRegistry` surface. */
+    getIssues(): readonly DiscoveryIssue[];
+    list(): Promise<UiManifestEntry[]>;
+    get(id: string): Promise<UiManifestEntry | undefined>;
+    getBundle(id: string): Promise<UiBundle | undefined>;
+    /**
+     * Richer bundle fetch — exposes the distinct "no colocated
+     * artifact AND no TSX entry" vs. "compile failed" states that
+     * `getBundle` collapses. The HTTP layer uses this directly so
+     * failures become actionable 4xx / 422 responses.
+     */
+    fetchBundle(id: string): Promise<LocalBundleResult>;
+    private ensureLoaded;
+}
+//# sourceMappingURL=local-registry.d.ts.map

package/dist/local-registry/local-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-registry.d.ts","sourceRoot":"","sources":["../../src/local-registry/local-registry.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,UAAU,EACV,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,8BAA8B,CAAC;AAOtC,OAAO,EAAyC,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAQzF,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,EAAE,UAAU,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAC1C;IACE,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACtE,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CACzE,CAAC;AAEN,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,eAAgB,YAAW,UAAU;IAChD,QAAQ,CAAC,YAAY,EAAE,sBAAsB,CAG3C;IAEF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;IACtC,OAAO,CAAC,WAAW,CAAmC;IACtD;oEACgE;IAChE,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAA6B;gBAEhC,OAAO,EAAE,sBAAsB;IAK3C;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;IAkBvE;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,IAAI;IAU9C,yDAAyD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,OAAO,CAAC,aAAa;IAYrB,kEAAkE;IAClE,SAAS,IAAI,SAAS,cAAc,EAAE;IAIhC,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAKlC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAMrD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAK1D;;;;;OAKG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;YA0D3C,YAAY;CAK3B"}

package/dist/local-registry/local-registry.js

@@ -0,0 +1,272 @@
+/**
+ * `LocalUiRegistry` — the first real implementation of
+ * `@ggui-ai/ui-registry`'s `UiRegistry` contract.
+ *
+ * Scope (compile-on-demand slice, 2026-04-18):
+ *
+ *   - Read-only. `capabilities.writable === false`;
+ *     `capabilities.observable === false`.
+ *   - Manifest-backed. Discovery runs against `ggui.json` +
+ *     `blueprints.include` globs via `./discovery.js` and is
+ *     cached in memory. `refresh()` re-runs discovery on demand;
+ *     file watching / `subscribe()` lands with a follow-up
+ *     HMR slice.
+ *   - `getBundle(id)` resolution order:
+ *       1. **Precompiled fast-path** — colocated `ggui.ui.js` or
+ *          `ggui.ui.mjs` beside the manifest. Lets a project with
+ *          its own build step opt out of compile-on-demand.
+ *       2. **Compile-on-demand** — resolve the manifest's
+ *          `entryPoint` (or a conventional `.tsx` filename beside
+ *          the manifest), run esbuild against it, return the
+ *          bundled ESM output. See `./compile-ui.ts`.
+ *       3. **Undefined** — the id is known to the registry but we
+ *          could find neither a precompiled artifact nor a TSX
+ *          entry. Per the `UiRegistry` contract, this is a valid
+ *          "no bundle" state, not an error — callers render the
+ *          "no preview available" affordance.
+ *
+ * Consumers that want to distinguish "missing entry" from "compile
+ * failed" need the richer {@link LocalBundleSource.fetchBundle}
+ * result — `getBundle` collapses both to the contract's
+ * `undefined` so the `UiRegistry` seam stays clean. The HTTP layer
+ * calls `fetchBundle` directly for actionable 4xx / 422 responses.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { discoverLocalUis, } from '@ggui-ai/project-config/node';
+import { compileUiOnDemand, COMPILED_BUNDLE_CONTENT_TYPE, resolveEntryFile, } from './compile-ui.js';
+import { createLocalWatcher } from './watcher.js';
+/** Accepted bundle filenames, in preference order. */
+const BUNDLE_FILENAMES = ['ggui.ui.js', 'ggui.ui.mjs'];
+/** Content-Type we claim for the compiled bundle. */
+const BUNDLE_CONTENT_TYPE = 'application/javascript+react';
+export class LocalUiRegistry {
+    capabilities = {
+        writable: false,
+        observable: true,
+    };
+    projectRoot;
+    manifest;
+    entriesById = new Map();
+    /** Absolute manifest dir → id. Rebuilt on every refresh so the
+     * watcher can attribute source-file changes to the right UI. */
+    manifestDirIndex = new Map();
+    lastIssues = [];
+    loaded = false;
+    watcher = null;
+    constructor(options) {
+        this.projectRoot = options.projectRoot;
+        this.manifest = options.manifest;
+    }
+    /**
+     * Force a re-scan of the filesystem against `blueprints.include`.
+     * Use after edits when `subscribe` isn't wired yet. The HTTP layer
+     * can call this on a PUT `/uis/refresh` or similar — not part of
+     * this slice.
+     */
+    async refresh() {
+        const result = await discoverLocalUis({
+            projectRoot: this.projectRoot,
+            manifest: this.manifest,
+        });
+        const next = new Map();
+        const dirIndex = new Map();
+        for (const ui of result.uis) {
+            next.set(ui.id, ui);
+            dirIndex.set(dirname(ui.manifestPath), ui.id);
+        }
+        this.entriesById = next;
+        this.manifestDirIndex = dirIndex;
+        this.lastIssues = result.issues;
+        this.loaded = true;
+        return { uiCount: result.uis.length, issues: result.issues };
+    }
+    /**
+     * Subscribe to registry change events. Flips
+     * `capabilities.observable` from spec to reality. Starts the
+     * underlying filesystem watcher on first call and keeps it
+     * alive until all listeners unsubscribe AND {@link close} is
+     * invoked (lifetime controlled by the enclosing dev server,
+     * not by subscriber churn — SSE clients come and go).
+     */
+    subscribe(listener) {
+        // Ensure the manifest dir index is populated before wiring the
+        // watcher — otherwise the first fs events arrive before
+        // `refresh()` has ever run and attribute-by-dir lookups return
+        // null. `ensureLoaded` is idempotent + cheap.
+        void this.ensureLoaded();
+        const watcher = this.ensureWatcher();
+        return watcher.subscribe(listener);
+    }
+    /** Shut down the watcher (if any) and drop listeners. */
+    async close() {
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    ensureWatcher() {
+        if (this.watcher)
+            return this.watcher;
+        this.watcher = createLocalWatcher({
+            projectRoot: this.projectRoot,
+            getManifestDirIndex: () => this.manifestDirIndex,
+            onManifestsChanged: async () => {
+                await this.refresh();
+            },
+        });
+        return this.watcher;
+    }
+    /** Diagnostic snapshot — NOT part of the `UiRegistry` surface. */
+    getIssues() {
+        return this.lastIssues;
+    }
+    async list() {
+        await this.ensureLoaded();
+        return Array.from(this.entriesById.values()).map(toEntry);
+    }
+    async get(id) {
+        await this.ensureLoaded();
+        const ui = this.entriesById.get(id);
+        return ui ? toEntry(ui) : undefined;
+    }
+    async getBundle(id) {
+        const result = await this.fetchBundle(id);
+        return result.kind === 'ok' ? result.bundle : undefined;
+    }
+    /**
+     * Richer bundle fetch — exposes the distinct "no colocated
+     * artifact AND no TSX entry" vs. "compile failed" states that
+     * `getBundle` collapses. The HTTP layer uses this directly so
+     * failures become actionable 4xx / 422 responses.
+     */
+    async fetchBundle(id) {
+        await this.ensureLoaded();
+        const ui = this.entriesById.get(id);
+        if (!ui)
+            return { kind: 'not-found' };
+        // Freshness rule (2026-04-18):
+        //   precompiled `.js` serves only if it's AT LEAST AS NEW as
+        //   the resolved TSX entry. If the TSX is newer — the user just
+        //   edited it — we recompile and ignore the stale precompiled
+        //   artifact. Stateless, watcher-independent, always correct.
+        //
+        //   Without this rule a developer's save of ggui.ui.tsx would be
+        //   silently masked by an older ggui.ui.js sitting beside it —
+        //   exactly the "edit TSX, still serves stale JS" failure mode
+        //   the HMR slice must not leave behind.
+        const precompiledPath = findColocatedBundlePath(ui.manifestPath);
+        const entryResolution = resolveEntryFile({
+            projectRoot: this.projectRoot,
+            manifestPath: ui.manifestPath,
+            manifest: ui.manifest,
+        });
+        const entryPath = 'entry' in entryResolution ? entryResolution.entry : null;
+        if (precompiledPath && shouldPreferPrecompiled(precompiledPath, entryPath)) {
+            const code = readFileSync(precompiledPath, 'utf-8');
+            return {
+                kind: 'ok',
+                bundle: { code, contentType: BUNDLE_CONTENT_TYPE },
+                source: 'precompiled',
+            };
+        }
+        // Compile-on-demand from the authored TSX entry (or surface
+        // missing-entry if neither precompiled nor entry exists).
+        const compiled = await compileUiOnDemand({
+            projectRoot: this.projectRoot,
+            manifestPath: ui.manifestPath,
+            manifest: ui.manifest,
+        });
+        if (compiled.kind === 'ok') {
+            return {
+                kind: 'ok',
+                bundle: { code: compiled.code, contentType: COMPILED_BUNDLE_CONTENT_TYPE },
+                source: 'compiled',
+            };
+        }
+        if (compiled.kind === 'missing-entry') {
+            return { kind: 'missing-entry', tried: compiled.tried };
+        }
+        return {
+            kind: 'compile-failed',
+            entry: compiled.entry,
+            errors: compiled.errors.map(toBundleMessage),
+            warnings: compiled.warnings.map(toBundleMessage),
+        };
+    }
+    async ensureLoaded() {
+        if (!this.loaded) {
+            await this.refresh();
+        }
+    }
+}
+function toBundleMessage(msg) {
+    const location = msg.location
+        ? {
+            file: msg.location.file,
+            line: msg.location.line,
+            column: msg.location.column,
+            length: msg.location.length,
+            lineText: msg.location.lineText,
+        }
+        : null;
+    return { text: msg.text, location };
+}
+function toEntry(ui) {
+    // `manifest.contentHash` is optional per the schema — authored
+    // manifests typically omit it until a compile step fills it in.
+    // The registry contract requires a non-undefined `contentHash`
+    // string; empty signals "no artifact-version pin yet", which is
+    // correct for a dev-only source registry.
+    return {
+        id: ui.id,
+        contentHash: ui.manifest.contentHash ?? '',
+        manifest: ui.manifest,
+    };
+}
+/**
+ * Locate the colocated precompiled bundle next to a manifest,
+ * if any. Returns the first matching filename per
+ * {@link BUNDLE_FILENAMES} preference or null. Does NOT read the
+ * bytes — the freshness comparison runs first, and we only
+ * actually read the file when we've decided to serve it.
+ */
+function findColocatedBundlePath(manifestPath) {
+    const dir = dirname(manifestPath);
+    for (const filename of BUNDLE_FILENAMES) {
+        const candidate = join(dir, filename);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Mtime-based freshness gate between a precompiled artifact and
+ * an authored TSX entry.
+ *
+ *   - No TSX entry at all → precompiled wins (nothing newer could
+ *     replace it; this is the pre-compile-on-demand case).
+ *   - TSX exists and is newer than precompiled → recompile. The
+ *     developer just edited; serving stale JS is the UX bug this
+ *     rule exists to prevent.
+ *   - Precompiled newer or equal → precompiled wins (user's own
+ *     build step ran; honour it).
+ *
+ * mtime-compare is stateless, watcher-independent, and correct
+ * even when subscribers are not connected.
+ */
+function shouldPreferPrecompiled(precompiledPath, entryPath) {
+    if (!entryPath)
+        return true;
+    try {
+        const pre = statSync(precompiledPath).mtimeMs;
+        const src = statSync(entryPath).mtimeMs;
+        return pre >= src;
+    }
+    catch {
+        // If a stat fails mid-check the safer call is to fall through
+        // to recompile — a compile-on-demand with a live entry file
+        // always produces fresh output.
+        return false;
+    }
+}