nudge-ui 0.2.0

package/dist/hosts/next/wrapper.js

@@ -0,0 +1,310 @@
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
+import { ensureSidecar } from "./sidecar.js";
+import { buildManifest } from "./manifest.js";
+import { nudgeUiRepositoryPackagePath } from "./repositoryScope.js";
+import { NUDGE_UI_ROUTE_PREFIX } from "../../transport/index.js";
+const NAMESPACE_PREFIX = NUDGE_UI_ROUTE_PREFIX.slice(0, -1);
+const SUPPORTED_NEXT_RANGE = ">=15.3 <17";
+/**
+ * Resolved from the package root so the path is identical whether this module
+ * runs from `src/hosts/next/` during development or `dist/hosts/next/` when
+ * installed. The loaders only ever exist in `dist`.
+ */
+function loaderPaths() {
+    const loaders = new URL("../../../dist/hosts/next/loaders/", import.meta.url);
+    return {
+        plugin: fileURLToPath(new URL("loader-plugin.cjs", loaders)),
+        identity: fileURLToPath(new URL("identity-loader.cjs", loaders)),
+    };
+}
+/** Absolute directory of a package installed in the host project, or null. */
+function hostPackageDir(root, name) {
+    try {
+        const require = createRequire(join(root, "package.json"));
+        return dirname(require.resolve(`${name}/package.json`));
+    }
+    catch {
+        return null;
+    }
+}
+/** Absolute path for an Adapter-owned package export, resolved beside this package. */
+function adapterPackageExport(specifier) {
+    try {
+        return createRequire(import.meta.url).resolve(specifier);
+    }
+    catch {
+        return null;
+    }
+}
+function relativeTurbopackAlias(root, target) {
+    const value = relative(root, target).split("\\").join("/");
+    return value.startsWith(".") ? value : `./${value}`;
+}
+function resolveNextVersion(root) {
+    try {
+        const require = createRequire(join(root, "package.json"));
+        return require("next/package.json").version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ADR-0010 gates instrumentation on the supported range: a RESOLVED version
+ * outside it fails closed (no registration) with a diagnostic — instrumenting
+ * an unsupported compiler risks breaking the host build. An unresolvable
+ * version gets the benefit of the doubt and proceeds with a diagnostic,
+ * since refusing to work because we could not read a version number would
+ * make the adapter brittle for no safety gain.
+ */
+function gateUnsupportedVersion(version) {
+    if (version && isVersionSupported(version))
+        return true;
+    console.warn(`[nudge-ui] Next.js ${version ?? "(version unavailable)"} is outside the tested range `
+        + `${SUPPORTED_NEXT_RANGE} (ADR-0010). Skipping instrumentation — remove `
+        + `withNudgeUi() or align versions to enable Nudge UI.`);
+    return false;
+}
+function isVersionSupported(version) {
+    const match = /^(\d+)\.(\d+)/.exec(version);
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    // >=15.3 <17
+    return (major === 15 && minor >= 3) || (major >= 16 && major < 17);
+}
+function collectUserRewriteSources(rewrites) {
+    return [
+        ...(rewrites.beforeFiles ?? []),
+        ...(rewrites.afterFiles ?? []),
+        ...(rewrites.fallback ?? []),
+    ]
+        .map((rule) => rule.source)
+        .filter((source) => source.startsWith(NAMESPACE_PREFIX));
+}
+/** Mirrors next/constants PHASE_DEVELOPMENT_SERVER. */
+export const DEVELOPMENT_SERVER_PHASE = "phase-development-server";
+/**
+ * Returns whether this config evaluation belongs to Next's development
+ * server. The phase argument is supplied by Next when it invokes a config
+ * factory, so object exports are converted to factories before any
+ * instrumentation can run. Keeping the phase check here means an object
+ * export cannot accidentally instrument `next build` when a caller has
+ * forced `NODE_ENV=development`.
+ */
+function isDevelopmentEvaluation(phase) {
+    return process.env.NODE_ENV === "development" && phase === DEVELOPMENT_SERVER_PHASE;
+}
+export function withNudgeUi(config = {}, options = {}) {
+    const factory = typeof config === "function"
+        ? config
+        : () => config;
+    return (phase) => {
+        const resolved = factory(phase);
+        if (!isDevelopmentEvaluation(phase))
+            return resolved;
+        return instrumentConfig(resolved, options);
+    };
+}
+function instrumentConfig(config, options) {
+    // Consumers pass their real NextConfig object; the structural subset is an
+    // internal view so this package stays typecheckable without next installed.
+    const source = config;
+    const root = process.cwd();
+    // Fail closed per ADR-0010 when the resolved version is unsupported.
+    if (!gateUnsupportedVersion(resolveNextVersion(root))) {
+        return config;
+    }
+    const sourceRoots = options.sourceRoots?.map((sourceRoot) => resolve(root, sourceRoot));
+    // ensureSidecar is a per-process singleton; awaiting it wherever the port
+    // is needed removes any config-evaluation race. The same authored roots
+    // reach token discovery so workspace CSS is visible to both integrations.
+    const sidecarPort = () => ensureSidecar(root, {
+        manifest: buildManifest({ root }),
+        tokens: true,
+        ...(sourceRoots ? { sourceRoots } : {}),
+    })
+        .then((handle) => handle.port)
+        .catch((error) => {
+        console.warn("[nudge-ui] sidecar failed to start:", error);
+        return 0;
+    });
+    const nextConfig = { ...source };
+    // --- transpilePackages -------------------------------------------------
+    // Workspace Nudge UI packages ship raw TypeScript that SWC refuses to
+    // compile from node_modules unless listed (see feature-plan appendix).
+    const nudgeUiPackages = [
+        "nudge-ui",
+        "../../inspector/index.ts",
+        "../../css/index.ts",
+    ];
+    const userTranspile = Array.isArray(source.transpilePackages)
+        ? source.transpilePackages
+        : [];
+    nextConfig.transpilePackages = [
+        ...userTranspile,
+        ...nudgeUiPackages.filter((name) => !userTranspile.includes(name)),
+    ];
+    // --- Turbopack rules (primary compiler) ---------------------------------
+    const turbopackRules = {
+        ...(source.turbopack?.rules ?? {}),
+    };
+    const paths = loaderPaths();
+    const loaderOptions = {
+        root,
+        ...(options.componentProtocols ? { componentProtocols: options.componentProtocols } : {}),
+        ...(sourceRoots ? { sourceRoots } : {}),
+    };
+    if (process.env.NUDGE_UI_NEXT_TURBOPACK_RULES !== "0") {
+        const identityRule = {
+            loaders: [{
+                    loader: paths.plugin,
+                    options: loaderOptions,
+                }],
+            // 'foreign' is Turbopack's builtin condition for dependency code, so
+            // `not: foreign` confines the loader to first-party sources. The path
+            // guard additionally keeps build output (.next) out of scope.
+            condition: {
+                all: [
+                    { not: "foreign" },
+                    { not: { path: "(**/)?\\.next/**" } },
+                    // Workspace symlinks are NOT foreign (they are source-backed), so
+                    // the Nudge UI packages themselves must be excluded explicitly:
+                    // instrumenting the inspector's own UI would wrap every control in
+                    // override boundaries and pollute the panel with identity attrs.
+                    // The list is shared with the loader's runtime scope check.
+                    {
+                        not: {
+                            path: nudgeUiRepositoryPackagePath,
+                        },
+                    },
+                ],
+            },
+        };
+        /**
+         * Rules are COMPOSED with any user rule for the same key by building a
+         * rule collection (Next supports arrays of items per glob) — silently
+         * overwriting host configuration is never acceptable.
+         */
+        const compose = (key, rule) => {
+            const existing = turbopackRules[key];
+            if (existing === undefined) {
+                turbopackRules[key] = rule;
+                return;
+            }
+            // [].concat flattens one level, so an existing collection stays flat.
+            turbopackRules[key] = [].concat(existing, rule);
+        };
+        compose("*.tsx", { ...identityRule });
+        compose("*.jsx", { ...identityRule });
+    }
+    // --- Single React instance (ADR-0004 via module resolution) -------------
+    // Nudge UI packages carry their own react dependency for standalone
+    // consumers. Without an alias, SWC resolves their `react` imports against
+    // those copies while the host application runs its own — two Reacts in one
+    // document, and inspector state updates silently stop rendering. Aliasing
+    // to the host project's copies pins one instance for every compilation.
+    const hostReact = hostPackageDir(root, "react");
+    const hostReactDom = hostPackageDir(root, "react-dom");
+    const componentRuntime = adapterPackageExport("nudge-ui/internal/component-runtime");
+    if (hostReact || hostReactDom || componentRuntime) {
+        const userAlias = source.turbopack?.resolveAlias ?? {};
+        nextConfig.turbopack = {
+            ...nextConfig.turbopack,
+            resolveAlias: {
+                ...(hostReact ? { react: relativeTurbopackAlias(root, hostReact) } : {}),
+                ...(hostReactDom ? { "react-dom": relativeTurbopackAlias(root, hostReactDom) } : {}),
+                ...(componentRuntime
+                    ? {
+                        "nudge-ui/internal/component-runtime": relativeTurbopackAlias(root, componentRuntime),
+                    }
+                    : {}),
+                ...userAlias,
+            },
+        };
+    }
+    nextConfig.turbopack = {
+        ...(nextConfig.turbopack ?? {}),
+        rules: turbopackRules,
+    };
+    // --- Webpack mode (secondary target, Stage 6 verifies parity) ----------
+    const userWebpack = source.webpack;
+    nextConfig.webpack = (webpackConfig, context) => {
+        const merged = userWebpack ? userWebpack(webpackConfig, context) : webpackConfig;
+        if (!context.dev)
+            return merged;
+        const module = (merged.module ?? {});
+        const resolveConfig = (merged.resolve ?? {});
+        const userAlias = (resolveConfig.alias ?? {});
+        const rules = Array.isArray(module.rules) ? [...module.rules] : [];
+        const paths = loaderPaths();
+        // Next 16 removed the webpack CSS pipeline entirely
+        // (nextjs.org/docs/messages/built-in-css-disabled): applications using
+        // stylesheets cannot run under `next dev --webpack` on 16 at all,
+        // with or without Nudge UI. Registration stays so Next 15.x within
+        // the supported range keeps working; flag the combination loudly.
+        const version = resolveNextVersion(root);
+        if (version && Number(version.split(".")[0]) >= 16) {
+            console.warn("[nudge-ui] Next.js " + version + " webpack dev mode has no CSS support "
+                + "(removed upstream); CSS-bearing applications will fail to compile "
+                + "independent of Nudge UI. Prefer Turbopack (default) or Next 15.x.");
+        }
+        rules.push({
+            test: /\.(tsx|jsx)$/,
+            exclude: /node_modules/,
+            enforce: "pre",
+            use: [{
+                    loader: paths.identity,
+                    options: loaderOptions,
+                }],
+        });
+        return {
+            ...merged,
+            resolve: {
+                ...resolveConfig,
+                alias: {
+                    ...(componentRuntime
+                        ? { "nudge-ui/internal/component-runtime": componentRuntime }
+                        : {}),
+                    ...userAlias,
+                },
+            },
+            module: { ...module, rules },
+        };
+    };
+    // --- Manifest transport rewrite ----------------------------------------
+    const proxyRewrite = (port) => ({
+        source: `${NUDGE_UI_ROUTE_PREFIX}:path*`,
+        destination: `http://127.0.0.1:${port}${NUDGE_UI_ROUTE_PREFIX}:path*`,
+    });
+    const resolveRewrites = async () => {
+        const port = await sidecarPort();
+        const userRewrites = typeof source.rewrites === "function"
+            ? await source.rewrites()
+            : source.rewrites;
+        const shape = Array.isArray(userRewrites)
+            ? { afterFiles: userRewrites }
+            : (userRewrites ?? {});
+        const collisions = collectUserRewriteSources(shape);
+        if (collisions.length > 0) {
+            console.warn("[nudge-ui] /__nudge_ui__ is a reserved namespace (ADR-0010); "
+                + "your rewrites also declare it and will be shadowed:", collisions);
+        }
+        return {
+            // Port 0 (sidecar failed to bind) yields a dead destination; the mount
+            // surfaces an honest fetch failure instead of silently pretending to
+            // work.
+            beforeFiles: [proxyRewrite(port), ...(shape.beforeFiles ?? [])],
+            afterFiles: shape.afterFiles ?? [],
+            fallback: shape.fallback ?? [],
+        };
+    };
+    // Preserve callability while keeping our async resolver.
+    nextConfig.rewrites = resolveRewrites;
+    // The structural view carries every original field through the spread;
+    // consumers keep their NextConfig typing via the generic passthrough.
+    return nextConfig;
+}

package/dist/hosts/static/cli.d.ts

@@ -0,0 +1,12 @@
+/** Parsed arguments for `nudge-ui serve`. */
+export interface ServeCommandOptions {
+    readonly rootDirectory: string;
+    readonly host: "127.0.0.1" | "::1" | "localhost";
+    readonly port: number;
+}
+/** Parses the standalone CLI's intentionally small command surface. */
+export declare function parseServeArguments(args: readonly string[], currentDirectory?: string): ServeCommandOptions;
+/** Starts the CLI server and waits until the process receives a termination signal. */
+export declare function runServeCommand(options: ServeCommandOptions): Promise<void>;
+/** Runs the standalone command. */
+export declare function main(args?: string[]): Promise<void>;

package/dist/hosts/static/cli.js

@@ -0,0 +1,77 @@
+import { resolve } from "node:path";
+import { createStandaloneServer } from "./server.js";
+/** Parses the standalone CLI's intentionally small command surface. */
+export function parseServeArguments(args, currentDirectory = process.cwd()) {
+    if (args[0] !== "serve") {
+        throw new Error("Usage: nudge-ui serve [directory] [--port <port>] [--host <loopback>]");
+    }
+    let directory = ".";
+    let host = "127.0.0.1";
+    let port = 4173;
+    let directoryProvided = false;
+    for (let index = 1; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--port") {
+            port = parsePort(args[++index]);
+        }
+        else if (argument.startsWith("--port=")) {
+            port = parsePort(argument.slice("--port=".length));
+        }
+        else if (argument === "--host") {
+            host = parseHost(args[++index]);
+        }
+        else if (argument.startsWith("--host=")) {
+            host = parseHost(argument.slice("--host=".length));
+        }
+        else if (argument.startsWith("-")) {
+            throw new Error(`Unknown option: ${argument}`);
+        }
+        else if (!directoryProvided) {
+            directory = argument;
+            directoryProvided = true;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${argument}`);
+        }
+    }
+    return { rootDirectory: resolve(currentDirectory, directory), host, port };
+}
+/** Starts the CLI server and waits until the process receives a termination signal. */
+export async function runServeCommand(options) {
+    const server = createStandaloneServer(options);
+    const address = await server.start();
+    console.log(`Nudge UI serving ${server.rootDirectory} at ${address.url}`);
+    await waitForTermination(server);
+}
+/** Runs the standalone command. */
+export async function main(args = process.argv.slice(2)) {
+    const options = parseServeArguments(args);
+    await runServeCommand(options);
+}
+async function waitForTermination(server) {
+    await new Promise((resolveWait) => {
+        let finished = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            void server.close().finally(resolveWait);
+        };
+        process.once("SIGINT", finish);
+        process.once("SIGTERM", finish);
+    });
+}
+function parsePort(value) {
+    if (!value)
+        throw new Error("--port requires a value.");
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new Error(`Port must be an integer from 0 to 65535; received ${value}.`);
+    }
+    return port;
+}
+function parseHost(value) {
+    if (value === "127.0.0.1" || value === "::1" || value === "localhost")
+        return value;
+    throw new Error(`Host must be loopback (127.0.0.1, ::1, or localhost); received ${value ?? ""}.`);
+}

package/dist/hosts/static/html/bootstrap.d.ts

@@ -0,0 +1,27 @@
+/** Options for source-preserving standalone bootstrap injection. */
+export interface StandaloneBootstrapOptions {
+    /** The browser client URL. */
+    readonly clientPath?: string;
+    /** The runtime manifest URL passed to the browser client. */
+    readonly manifestPath?: string;
+}
+/** The result of injecting the standalone bootstrap into one HTML response. */
+export interface StandaloneBootstrapResult {
+    /** The response source after any missing bootstrap nodes are inserted. */
+    readonly html: string;
+    /** Whether at least one node was inserted. */
+    readonly injected: boolean;
+}
+/**
+ * Adds the standalone mount and external client script to an HTML response.
+ *
+ * The function only inserts text at an existing HTML boundary. It does not
+ * parse and reserialize the document, so authored bytes remain unchanged
+ * except for the server-owned nodes. Marker checks make a second response
+ * pass idempotent.
+ *
+ * @param html The transformed HTML response body.
+ * @param options Bootstrap URLs and mount identity.
+ * @returns The response body and whether anything was added.
+ */
+export declare function injectStandaloneBootstrap(html: string, options?: StandaloneBootstrapOptions): StandaloneBootstrapResult;

package/dist/hosts/static/html/bootstrap.js

@@ -0,0 +1,93 @@
+import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_MANIFEST_PATH, } from "../manifest.js";
+import { parse } from "parse5";
+const CLIENT_MARKER = "data-nudge-ui-client";
+const MOUNT_MARKER = "data-nudge-ui-mount";
+/**
+ * Adds the standalone mount and external client script to an HTML response.
+ *
+ * The function only inserts text at an existing HTML boundary. It does not
+ * parse and reserialize the document, so authored bytes remain unchanged
+ * except for the server-owned nodes. Marker checks make a second response
+ * pass idempotent.
+ *
+ * @param html The transformed HTML response body.
+ * @param options Bootstrap URLs and mount identity.
+ * @returns The response body and whether anything was added.
+ */
+export function injectStandaloneBootstrap(html, options = {}) {
+    const clientPath = options.clientPath ?? NUDGE_UI_CLIENT_PATH;
+    const manifestPath = options.manifestPath ?? NUDGE_UI_MANIFEST_PATH;
+    const document = parse(html, { sourceCodeLocationInfo: true });
+    const sourceFacts = inspectSource(document, clientPath);
+    const nodes = [];
+    if (!sourceFacts.hasMount) {
+        nodes.push(`<div id="${NUDGE_UI_MOUNT_ID}" ${MOUNT_MARKER}></div>`);
+    }
+    if (!sourceFacts.hasClient) {
+        nodes.push(`<script type="module" src="${escapeAttributeValue(clientPath)}" ${CLIENT_MARKER} data-nudge-ui-manifest="${escapeAttributeValue(manifestPath)}"></script>`);
+    }
+    if (nodes.length === 0)
+        return { html, injected: false };
+    const injection = `\n${nodes.join("\n")}\n`;
+    const offset = sourceFacts.bodyEndOffset ?? sourceFacts.htmlEndOffset ?? html.length;
+    return {
+        html: `${html.slice(0, offset)}${injection}${html.slice(offset)}`,
+        injected: true,
+    };
+}
+function inspectSource(document, clientPath) {
+    const facts = {
+        hasMount: false,
+        hasClient: false,
+        bodyEndOffset: null,
+        htmlEndOffset: null,
+    };
+    let body = null;
+    visitElements(document, (element) => {
+        if (element.namespaceURI !== "http://www.w3.org/1999/xhtml")
+            return;
+        const tagName = element.tagName.toLowerCase();
+        if (tagName === "body")
+            body = element;
+        if (tagName === "script"
+            && (attributeValue(element, CLIENT_MARKER) !== null
+                || attributeValue(element, "src") === clientPath)) {
+            facts.hasClient = true;
+        }
+        const endOffset = element.sourceCodeLocation?.endTag?.startOffset;
+        if (tagName === "body" && endOffset !== undefined)
+            facts.bodyEndOffset = endOffset;
+        if (tagName === "html" && endOffset !== undefined)
+            facts.htmlEndOffset = endOffset;
+    });
+    // Only live body descendants can reserve the mount. Template content is
+    // inert and must not suppress injection into the document.
+    if (body) {
+        visitElements(body, (element) => {
+            if (element !== body && attributeValue(element, "id") === NUDGE_UI_MOUNT_ID) {
+                facts.hasMount = true;
+            }
+        });
+    }
+    return facts;
+}
+function visitElements(parent, visit) {
+    for (const child of parent.childNodes) {
+        if (!("tagName" in child) || typeof child.tagName !== "string")
+            continue;
+        if (child.tagName.toLowerCase() === "template")
+            continue;
+        visit(child);
+        visitElements(child, visit);
+    }
+}
+function attributeValue(element, name) {
+    return element.attrs.find((attribute) => attribute.name === name)?.value ?? null;
+}
+function escapeAttributeValue(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}

package/dist/hosts/static/index.d.ts

@@ -0,0 +1,4 @@
+export { instrumentSourceHtml, type HtmlIdentityDiagnostic, type HtmlIdentityDiagnosticCode, type HtmlIdentityResult, } from "../../html/identity.js";
+export { injectStandaloneBootstrap, type StandaloneBootstrapOptions, type StandaloneBootstrapResult, } from "./html/bootstrap.js";
+export { createStandaloneRuntimeManifest, NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, type StandaloneRuntimeManifest, } from "./manifest.js";
+export { contentTypeForPath, createStandaloneProjectId, createStandaloneServer, isReservedNudgeUiRoute, resolveStaticFile, type StandaloneServer, type StandaloneServerAddress, type StandaloneServerOptions, type StaticFileResolution, } from "./server.js";

package/dist/hosts/static/index.js

@@ -0,0 +1,4 @@
+export { instrumentSourceHtml, } from "../../html/identity.js";
+export { injectStandaloneBootstrap, } from "./html/bootstrap.js";
+export { createStandaloneRuntimeManifest, NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "./manifest.js";
+export { contentTypeForPath, createStandaloneProjectId, createStandaloneServer, isReservedNudgeUiRoute, resolveStaticFile, } from "./server.js";

package/dist/hosts/static/manifest.d.ts

@@ -0,0 +1,18 @@
+import type { NudgeUiClientManifest } from "../../inspector/clientManifest.js";
+import type { ProjectTokenSnapshot } from "../../project/tokens.js";
+export { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
+/** The serializable runtime document sent to a standalone client. */
+export interface StandaloneRuntimeManifest extends NudgeUiClientManifest {
+}
+/**
+ * Creates the first valid static-HTML runtime snapshot.
+ *
+ * Stage 4 replaces the empty token arrays with the CSS token-inventory
+ * snapshot. Keeping this constructor here makes the manifest contract
+ * explicit and prevents the server from manufacturing a partial runtime
+ * configuration.
+ *
+ * @param projectId The deterministic identity of the served project.
+ * @returns A complete runtime manifest with no framework contracts or tokens.
+ */
+export declare function createStandaloneRuntimeManifest(projectId: string, tokenSnapshot?: ProjectTokenSnapshot, revision?: number): StandaloneRuntimeManifest;

package/dist/hosts/static/manifest.js

@@ -0,0 +1,51 @@
+import { NUDGE_UI_MANIFEST_VERSION, NUDGE_UI_RELOAD_PATH } from "../../transport/index.js";
+export { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
+/**
+ * Creates the first valid static-HTML runtime snapshot.
+ *
+ * Stage 4 replaces the empty token arrays with the CSS token-inventory
+ * snapshot. Keeping this constructor here makes the manifest contract
+ * explicit and prevents the server from manufacturing a partial runtime
+ * configuration.
+ *
+ * @param projectId The deterministic identity of the served project.
+ * @returns A complete runtime manifest with no framework contracts or tokens.
+ */
+export function createStandaloneRuntimeManifest(projectId, tokenSnapshot = emptyTokenSnapshot(), revision = 0) {
+    return {
+        version: NUDGE_UI_MANIFEST_VERSION,
+        revision,
+        runtime: {
+            projectId,
+            host: "static-html",
+            framework: "HTML",
+            stylingSystem: "CSS custom properties",
+            // Canvas shares the Vite host's controller/renderer runtime (ADR-0012):
+            // every served document carries the bootstrap, so card iframes boot as
+            // renderers without host-specific code.
+            capabilities: { canvas: true, componentSemantics: false },
+            tokenCatalog: tokenSnapshot.tokenCatalog,
+            tokens: tokenSnapshot.tokens,
+            tokenDiagnostics: tokenSnapshot.tokenDiagnostics,
+            tokenGeneration: tokenSnapshot.tokenGeneration,
+            componentContracts: [],
+        },
+        document: {
+            runtimeIdentity: "static-html",
+            stylesheetOrder: "browser",
+        },
+        reload: {
+            endpoint: NUDGE_UI_RELOAD_PATH,
+            strategy: "reload-document",
+            events: ["ready", "reload"],
+        },
+    };
+}
+function emptyTokenSnapshot() {
+    return {
+        tokenCatalog: [],
+        tokens: [],
+        tokenDiagnostics: [],
+        tokenGeneration: "empty",
+    };
+}

package/dist/hosts/static/server.d.ts

@@ -0,0 +1,72 @@
+import { type Server } from "node:http";
+import { type StandaloneRuntimeManifest } from "./manifest.js";
+/** Options for the loopback-only standalone static server. */
+export interface StandaloneServerOptions {
+    /** The explicit directory whose files may be served. */
+    readonly rootDirectory: string;
+    /** The loopback address to bind. Defaults to `127.0.0.1`. */
+    readonly host?: "127.0.0.1" | "::1" | "localhost";
+    /** The TCP port. Use `0` to ask the operating system for an available port. */
+    readonly port?: number;
+    /** The prebuilt browser client artifact. */
+    readonly clientPath?: string;
+    /** Override the deterministic project identity in tests or embedding hosts. */
+    readonly projectId?: string;
+    /** Debounce interval for source changes before one reload revision. */
+    readonly watchDebounceMs?: number;
+}
+/** A canonical file resolved below the configured project root. */
+export interface StaticFileResolution {
+    /** The canonical file path on disk. */
+    readonly absolutePath: string;
+    /** The slash-separated project-relative path used for source identity. */
+    readonly projectPath: string;
+}
+/** The address returned after the server starts listening. */
+export interface StandaloneServerAddress {
+    readonly host: string;
+    readonly port: number;
+    readonly url: string;
+}
+/** The running standalone server and its lifecycle methods. */
+export interface StandaloneServer {
+    readonly httpServer: Server;
+    readonly rootDirectory: string;
+    readonly projectId: string;
+    readonly manifest: StandaloneRuntimeManifest;
+    start(): Promise<StandaloneServerAddress>;
+    close(): Promise<void>;
+}
+/**
+ * Creates a Nudge UI-owned static server for one explicit project root.
+ *
+ * The server binds to loopback, reserves its own route namespace, and only
+ * reads prototype files. HTML instrumentation and bootstrap nodes exist in
+ * response memory; the configured source directory is never rewritten.
+ *
+ * @param options Server root, address, port, and client artifact options.
+ * @returns A server that has not started listening yet.
+ * @throws If the root is missing, not a directory, or the host is not loopback.
+ */
+export declare function createStandaloneServer(options: StandaloneServerOptions): StandaloneServer;
+/**
+ * Resolves one URL pathname to a canonical file under the project root.
+ *
+ * URL decoding occurs before path normalization, which makes encoded dot
+ * segments subject to the same confinement check as ordinary traversal. The
+ * canonical existing ancestor check also rejects a symlink that escapes the
+ * root when the requested leaf does not yet exist. Hidden path segments are
+ * refused, including encoded and multiply encoded forms, and a visible
+ * symlink cannot be used to reach a hidden target.
+ *
+ * @param rootDirectory The configured project root.
+ * @param requestPath A request target or URL pathname.
+ * @returns A file resolution, or `null` for malformed, missing, or unsafe paths.
+ */
+export declare function resolveStaticFile(rootDirectory: string, requestPath: string): StaticFileResolution | null;
+/** Returns the deterministic project identity used for session persistence. */
+export declare function createStandaloneProjectId(rootDirectory: string): string;
+/** Returns a common response content type for a project-relative file. */
+export declare function contentTypeForPath(filePath: string): string;
+/** Returns whether a decoded pathname belongs to the server-owned route space. */
+export declare function isReservedNudgeUiRoute(pathname: string): boolean;