@norskvideo/ctl-sdk 0.1.0

package/base.css

@@ -0,0 +1,53 @@
+/*
+ * Base stylesheet shared by every product frontend. Products import this and
+ * state no font/theme/reset opinion of their own — so norsk-ctl, the product
+ * config UIs, and Studio all render identically.
+ *
+ *   @import "@norskvideo/ctl-sdk/base.css";
+ *
+ * Geist Sans + Geist Mono (Vercel, SIL OFL 1.1 — see fonts/Geist-LICENSE.txt),
+ * vendored once here as single variable woff2 files so nothing pulls a font
+ * from a CDN and every surface renders the same glyphs. Norsk Studio must be
+ * moved onto the same Geist files to stay in sync (see fonts/README.md).
+ */
+@import "tailwindcss";
+
+@font-face {
+  font-family: "Geist";
+  font-style: normal;
+  font-weight: 100 900; /* variable range → no faux bold */
+  font-display: swap;
+  src: url("./fonts/Geist.woff2") format("woff2-variations"),
+       url("./fonts/Geist.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Geist Mono";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("./fonts/GeistMono.woff2") format("woff2-variations"),
+       url("./fonts/GeistMono.woff2") format("woff2");
+}
+
+@theme {
+  --color-zinc-850: #1f1f23;
+  --font-sans: "Geist", ui-sans-serif, system-ui, sans-serif;
+  --font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+::-webkit-scrollbar-track {
+  background: #18181b;
+}
+::-webkit-scrollbar-thumb {
+  background: #3f3f46;
+  border-radius: 3px;
+}

package/browser.d.ts

@@ -0,0 +1,8 @@
+export * from "./manifest-schema.js";
+export * from "./parsing.js";
+export * from "./product-error.js";
+export * from "./product-template-error.js";
+export * from "./product-template-parsing.js";
+export * from "./product-template-record.js";
+export * from "./product-types.js";
+export * from "./validate.js";

package/browser.js

@@ -0,0 +1,11 @@
+// Browser-safe surface: types, schemas, parsers, validators.
+// Anything with Node-only deps (fs, child_process, express) lives in the
+// default entry only.
+export * from "./manifest-schema.js";
+export * from "./parsing.js";
+export * from "./product-error.js";
+export * from "./product-template-error.js";
+export * from "./product-template-parsing.js";
+export * from "./product-template-record.js";
+export * from "./product-types.js";
+export * from "./validate.js";

package/capabilities-router.d.ts

@@ -0,0 +1,9 @@
+import { Router } from "express";
+/**
+ * Serves a product's self-describing capabilities at `GET /capabilities`,
+ * relative to wherever the router is mounted (products mount it under `/api`).
+ *
+ * Generic over `T` so each product's distinct capabilities type flows through
+ * unchanged — the factory carries no product knowledge and no flags.
+ */
+export declare function createCapabilitiesRouter<T>(buildCapabilities: () => T): Router;

package/capabilities-router.js

@@ -0,0 +1,15 @@
+import { Router } from "express";
+/**
+ * Serves a product's self-describing capabilities at `GET /capabilities`,
+ * relative to wherever the router is mounted (products mount it under `/api`).
+ *
+ * Generic over `T` so each product's distinct capabilities type flows through
+ * unchanged — the factory carries no product knowledge and no flags.
+ */
+export function createCapabilitiesRouter(buildCapabilities) {
+    const router = Router();
+    router.get("/capabilities", (_req, res) => {
+        res.json(buildCapabilities());
+    });
+    return router;
+}

package/cjs-interop.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Interop for the TypeScript-compiled CommonJS modules the Norsk Studio
+ * libraries ship (`exports.default = fn` plus an `__esModule` marker).
+ *
+ * How such a module reaches an ESM importer depends on WHO loaded it, and the
+ * shapes are not interchangeable:
+ *
+ * - Left external and required at runtime by bun → `.default` is the function.
+ * - Bundled by `bun build` → the emitted helper is
+ *   `__toESM(require_mod(), /* isNodeMode *\/ 1)`, and that helper reads
+ *   `isNodeMode || !mod || !mod.__esModule` — short-circuiting on isNodeMode
+ *   before it ever tests `__esModule`. So `default` is set to the entire
+ *   `module.exports`, and the real function sits at `.default.default`.
+ *
+ * A plain `import fn from "..."` therefore works or breaks purely on whether
+ * the importing package's build marked the library external — an invisible
+ * coupling between a bundler flag and a runtime call. Probe's product-template
+ * generation hit exactly this: `shared`'s build externalises the studio libs,
+ * `backend`'s does not, so the same source worked in one bundle and threw
+ * "import_info.default is not a function" in the other.
+ *
+ * Route every studio-library default import through here and the call site
+ * stops caring how it was built.
+ */
+/**
+ * Extract the callable default export of a CommonJS-compiled module, whatever
+ * interop shape it arrived in.
+ *
+ * @param mod The imported module namespace, or the module itself.
+ * @param specifier What was imported — used in the error, so a failure names the
+ *   module instead of a mangled bundler local like `import_info`.
+ */
+export declare function callableDefault<T extends (...args: never[]) => unknown>(mod: unknown, specifier: string): T;

package/cjs-interop.js

@@ -0,0 +1,61 @@
+/**
+ * Interop for the TypeScript-compiled CommonJS modules the Norsk Studio
+ * libraries ship (`exports.default = fn` plus an `__esModule` marker).
+ *
+ * How such a module reaches an ESM importer depends on WHO loaded it, and the
+ * shapes are not interchangeable:
+ *
+ * - Left external and required at runtime by bun → `.default` is the function.
+ * - Bundled by `bun build` → the emitted helper is
+ *   `__toESM(require_mod(), /* isNodeMode *\/ 1)`, and that helper reads
+ *   `isNodeMode || !mod || !mod.__esModule` — short-circuiting on isNodeMode
+ *   before it ever tests `__esModule`. So `default` is set to the entire
+ *   `module.exports`, and the real function sits at `.default.default`.
+ *
+ * A plain `import fn from "..."` therefore works or breaks purely on whether
+ * the importing package's build marked the library external — an invisible
+ * coupling between a bundler flag and a runtime call. Probe's product-template
+ * generation hit exactly this: `shared`'s build externalises the studio libs,
+ * `backend`'s does not, so the same source worked in one bundle and threw
+ * "import_info.default is not a function" in the other.
+ *
+ * Route every studio-library default import through here and the call site
+ * stops caring how it was built.
+ */
+/** How many `.default` levels to unwrap before giving up (guards cycles). */
+const MAX_UNWRAP = 4;
+/**
+ * Extract the callable default export of a CommonJS-compiled module, whatever
+ * interop shape it arrived in.
+ *
+ * @param mod The imported module namespace, or the module itself.
+ * @param specifier What was imported — used in the error, so a failure names the
+ *   module instead of a mangled bundler local like `import_info`.
+ */
+export function callableDefault(mod, specifier) {
+    let candidate = mod;
+    for (let depth = 0; depth <= MAX_UNWRAP; depth++) {
+        if (typeof candidate === "function")
+            return candidate;
+        if (candidate === null || typeof candidate !== "object")
+            break;
+        const next = candidate.default;
+        if (next === undefined || next === candidate)
+            break;
+        candidate = next;
+    }
+    throw new Error(`'${specifier}' has no callable default export (found ${describe(mod)}). ` +
+        "A CommonJS module bundled by bun exposes module.exports as `default`, so the function " +
+        "can sit one level deeper — use callableDefault() rather than a plain default import.");
+}
+/** Describe what actually arrived, shallowly — enough to debug, no dumping. */
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (typeof value !== "object")
+        return typeof value;
+    const keys = Object.keys(value).slice(0, 8);
+    return `an object with keys [${keys.join(", ")}]`;
+}

package/components/ProductIframe.d.ts

@@ -0,0 +1,37 @@
+export type SubmitResult = {
+    ok: true;
+    formValues: Record<string, unknown>;
+} | {
+    ok: false;
+    error?: string;
+};
+export type ProductIframeHandle = {
+    submit: () => Promise<SubmitResult>;
+};
+export declare const ProductIframe: import("react").ForwardRefExoticComponent<{
+    productName: string;
+    configScreenUrl: string;
+    /**
+     * Fires when the iframe emits a `validity` postMessage. Parent forms
+     * use this to disable Save / Save & Launch while the form is invalid.
+     * Default before any validity message arrives is treat-as-valid —
+     * products that don't emit validity shouldn't be blocked.
+     */
+    onValidityChange?: (valid: boolean, errors: string[]) => void;
+    /**
+     * Fires when the iframe emits a `suggest-name` postMessage — a product
+     * template name derived from the product's current choices (e.g. template +
+     * release). The runner uses it as placeholder/prefill for its own
+     * product-template-name field while that field is untouched. Products that
+     * don't emit it leave the field's default behaviour unchanged.
+     */
+    onSuggestName?: (name: string) => void;
+    /**
+     * Optional product-template/launch context forwarded verbatim in the `init`
+     * payload (as `launchContext`). Used by the instance-launch config screen
+     * (not the template-configure screen) so the product can prefill against
+     * the product template being launched — e.g. its parameters and current
+     * defaults.
+     */
+    launchContext?: Record<string, unknown>;
+} & import("react").RefAttributes<ProductIframeHandle>>;

package/components/ProductIframe.js

@@ -0,0 +1,119 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from "react";
+const PROTOCOL_VERSION = 1;
+const SUBMIT_TIMEOUT_MS = 30_000;
+function resolveSrc(productName, configScreenUrl) {
+    const path = configScreenUrl.startsWith("/") ? configScreenUrl : `/${configScreenUrl}`;
+    return `/products/${encodeURIComponent(productName)}${path}`;
+}
+export const ProductIframe = forwardRef(function ProductIframe({ productName, configScreenUrl, onValidityChange, onSuggestName, launchContext }, ref) {
+    const iframeRef = useRef(null);
+    const [height, setHeight] = useState(420);
+    const [valid, setValid] = useState(true);
+    const [errors, setErrors] = useState(null);
+    const submitResolverRef = useRef(null);
+    // Ref-stored callback so the message listener (mount-only useEffect) can
+    // always reach the latest one without re-binding.
+    const onValidityChangeRef = useRef(onValidityChange);
+    useEffect(() => {
+        onValidityChangeRef.current = onValidityChange;
+    }, [onValidityChange]);
+    const onSuggestNameRef = useRef(onSuggestName);
+    useEffect(() => {
+        onSuggestNameRef.current = onSuggestName;
+    }, [onSuggestName]);
+    const src = resolveSrc(productName, configScreenUrl);
+    useEffect(() => {
+        const onMessage = (event) => {
+            if (event.source !== iframeRef.current?.contentWindow)
+                return;
+            const data = event.data;
+            if (!data || typeof data !== "object")
+                return;
+            if (data.v !== PROTOCOL_VERSION)
+                return;
+            const payload = data.payload ?? {};
+            switch (data.type) {
+                case "ready":
+                case "resize":
+                    if (typeof payload.height === "number" && payload.height > 0)
+                        setHeight(payload.height);
+                    break;
+                case "validity": {
+                    const v = typeof payload.valid === "boolean" ? payload.valid : true;
+                    const errs = Array.isArray(payload.errors) ? payload.errors : [];
+                    setValid(v);
+                    setErrors(errs.length ? errs : null);
+                    onValidityChangeRef.current?.(v, errs);
+                    break;
+                }
+                case "suggest-name": {
+                    if (typeof payload.name === "string" && payload.name)
+                        onSuggestNameRef.current?.(payload.name);
+                    break;
+                }
+                case "submit-result": {
+                    const resolve = submitResolverRef.current;
+                    submitResolverRef.current = null;
+                    if (!resolve)
+                        break;
+                    // New shape: { ok: true, formValues } / { ok: false, error }.
+                    // Old shape (option-a): { ok: true, productTemplate, ... }. If we see
+                    // the old shape, fall through with an empty formValues so the
+                    // runner-side error message is the one the user sees.
+                    if (payload?.ok === true && payload.formValues && typeof payload.formValues === "object") {
+                        resolve({ ok: true, formValues: payload.formValues });
+                    }
+                    else if (payload?.ok === true) {
+                        console.warn("[ProductIframe] product emitted legacy submit-result without `formValues`; " +
+                            "update the product to send `{ ok: true, formValues: {...} }`");
+                        resolve({ ok: false, error: "product returned legacy submit-result shape (no formValues)" });
+                    }
+                    else {
+                        resolve({ ok: false, error: typeof payload?.error === "string" ? payload.error : undefined });
+                    }
+                    break;
+                }
+                // dirty / request-cancel / navigate intentionally ignored in v1
+            }
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, []);
+    // Path prefix where the product is mounted on the runner's origin. The
+    // product's router (e.g. React Router's `basename`) needs this to resolve
+    // routes correctly when iframed; standalone mode can ignore it.
+    const basename = `/products/${encodeURIComponent(productName)}`;
+    // Ref so the mount-time onLoad closure always sends the latest context.
+    const launchContextRef = useRef(launchContext);
+    launchContextRef.current = launchContext;
+    const sendInit = useCallback(() => {
+        iframeRef.current?.contentWindow?.postMessage({
+            v: PROTOCOL_VERSION,
+            type: "init",
+            payload: {
+                instanceContext: { basename },
+                theme: "dark",
+                locale: "en",
+                ...(launchContextRef.current ? { launchContext: launchContextRef.current } : {}),
+            },
+        }, "*");
+    }, [basename]);
+    useImperativeHandle(ref, () => ({
+        submit: () => new Promise((resolve) => {
+            if (!iframeRef.current?.contentWindow) {
+                resolve({ ok: false, error: "Iframe not loaded" });
+                return;
+            }
+            submitResolverRef.current = resolve;
+            iframeRef.current.contentWindow.postMessage({ v: PROTOCOL_VERSION, type: "submit", payload: {} }, "*");
+            setTimeout(() => {
+                if (submitResolverRef.current === resolve) {
+                    submitResolverRef.current = null;
+                    resolve({ ok: false, error: `Iframe did not respond within ${SUBMIT_TIMEOUT_MS / 1000}s` });
+                }
+            }, SUBMIT_TIMEOUT_MS);
+        }),
+    }));
+    return (_jsxs("div", { className: "rounded border border-zinc-700 bg-zinc-950 overflow-hidden", children: [_jsx("iframe", { ref: iframeRef, src: src, title: `${productName} configuration`, onLoad: sendInit, className: "w-full block border-0", style: { height } }), !valid && (_jsx("p", { className: "text-xs text-amber-400 px-3 py-1.5 border-t border-zinc-800", children: errors?.length ? errors.join("; ") : "Form has validation errors." }))] }));
+});

package/components/ProductTemplateBuildForm.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Configure-iframe form. Produces a *product template*, NOT a running instance.
+ * Two submit paths:
+ *  - "Save"            — caller persists the product template, then we close.
+ *  - "Save & Launch…"  — caller persists the product template and is expected to
+ *                         hand off to its launch flow.
+ *
+ * No runner-side mode toggle here: the iframe is pure product UX. Caller
+ * supplies the actual "save" implementation via `onSubmit`, so this works
+ * for both the runner (POST /api/product-templates/build → store on disk) and the
+ * manager (POST /api/instances → submit to the manager-daemon as
+ * ProductTemplateRef.inline_tar).
+ */
+export type ProductTemplateBuildRequest = {
+    productName: string;
+    productTemplateName: string;
+    formValues: Record<string, unknown>;
+};
+export type ProductTemplateBuildOutcome<TProductTemplate> = {
+    ok: true;
+    productTemplate: TProductTemplate;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function ProductTemplateBuildForm<TProductTemplate>({ productName, configScreenUrl, onClose, onSubmit, onSaved, onSavedAndLaunch, }: {
+    productName: string;
+    configScreenUrl: string | null;
+    onClose: () => void;
+    /**
+     * Persists the product template. Implementation owns the wire protocol —
+     * runner stores on disk; manager submits to manager-daemon. Returns the
+     * resulting product-template record (consumer-defined shape) on success.
+     */
+    onSubmit: (req: ProductTemplateBuildRequest) => Promise<ProductTemplateBuildOutcome<TProductTemplate>>;
+    /** Save-only: product template persisted, form closes. */
+    onSaved?: (productTemplate: TProductTemplate) => void;
+    /** Save & continue: caller transitions to its launch flow. */
+    onSavedAndLaunch?: (productTemplate: TProductTemplate) => void;
+}): import("react").JSX.Element;

package/components/ProductTemplateBuildForm.js

@@ -0,0 +1,81 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { X } from "lucide-react";
+import { useRef, useState } from "react";
+import toast from "react-hot-toast";
+import { validateInstanceId } from "../validate.js";
+import { ProductIframe } from "./ProductIframe.js";
+import { useUIPrimitives } from "./ui-primitives.js";
+export function ProductTemplateBuildForm({ productName, configScreenUrl, onClose, onSubmit, onSaved, onSavedAndLaunch, }) {
+    const { Button, Input, Label } = useUIPrimitives();
+    const [productTemplateName, setProductTemplateName] = useState("");
+    // The iframe can suggest a name derived from its current choices (#317).
+    // We prefill the field with it while the operator hasn't typed anything,
+    // so changing template/release keeps the suggestion live; once they edit
+    // the field, their value wins and we stop syncing.
+    const [suggestedName, setSuggestedName] = useState("");
+    const [nameTouched, setNameTouched] = useState(false);
+    const [submitting, setSubmitting] = useState(false);
+    // Treat-as-valid until the iframe says otherwise (per the v1 contract:
+    // products that don't care about validation aren't required to emit).
+    const [iframeValid, setIframeValid] = useState(true);
+    const iframeRef = useRef(null);
+    const handleSuggestName = (name) => {
+        setSuggestedName(name);
+        if (!nameTouched)
+            setProductTemplateName(name);
+    };
+    const nameValidation = productTemplateName ? validateInstanceId(productTemplateName) : null;
+    const productTemplateNameError = nameValidation?.status === "error" ? nameValidation.message : null;
+    const canSubmit = !!productTemplateName && !productTemplateNameError && !submitting && iframeValid;
+    // Internal helper. Returns the saved product template on success (so the
+    // caller can hand it off to its launch flow without waiting for a refetch),
+    // null on failure.
+    const saveProductTemplate = async () => {
+        if (!iframeRef.current) {
+            toast.error("Configuration not ready");
+            return null;
+        }
+        const result = await iframeRef.current.submit();
+        if (!result.ok) {
+            toast.error(result.error ?? "Configuration submission failed");
+            return null;
+        }
+        const outcome = await onSubmit({ productName, productTemplateName, formValues: result.formValues });
+        if (!outcome.ok) {
+            toast.error(`Save product template failed: ${outcome.error}`);
+            return null;
+        }
+        return outcome.productTemplate;
+    };
+    const handleSave = async (e) => {
+        e.preventDefault();
+        setSubmitting(true);
+        try {
+            const pt = await saveProductTemplate();
+            if (!pt)
+                return;
+            toast.success(`Product template '${productTemplateName}' saved`);
+            onSaved?.(pt);
+            onClose();
+        }
+        finally {
+            setSubmitting(false);
+        }
+    };
+    const handleSaveAndLaunch = async () => {
+        setSubmitting(true);
+        try {
+            const pt = await saveProductTemplate();
+            if (!pt)
+                return;
+            onSavedAndLaunch?.(pt);
+        }
+        finally {
+            setSubmitting(false);
+        }
+    };
+    return (_jsxs("div", { className: "mb-6 rounded-lg border border-zinc-700 bg-zinc-900 p-4", children: [_jsxs("div", { className: "flex items-center justify-between mb-4", children: [_jsxs("div", { children: [_jsxs("h4", { className: "text-sm font-semibold text-zinc-100", children: ["Create ", productName, " product template"] }), _jsx("p", { className: "text-xs text-zinc-500 mt-0.5", children: "Saves a reusable product template. Launch instances from it later." })] }), _jsx("button", { type: "button", onClick: onClose, className: "text-zinc-500 hover:text-zinc-300", children: _jsx(X, { size: 14 }) })] }), _jsxs("form", { onSubmit: handleSave, className: "space-y-4", children: [_jsxs("div", { children: [_jsx(Label, { children: "Product template name *" }), _jsx(Input, { value: productTemplateName, onChange: (e) => {
+                                    setNameTouched(true);
+                                    setProductTemplateName(e.target.value);
+                                }, placeholder: suggestedName || `e.g. ${productName}-prod`, required: true }), productTemplateNameError ? (_jsx("p", { className: "text-xs text-red-400 mt-1", children: productTemplateNameError })) : (_jsx("p", { className: "text-xs text-zinc-500 mt-1", children: "Lowercase letters, numbers, and hyphens only. Used to launch instances later." }))] }), configScreenUrl ? (_jsx(ProductIframe, { ref: iframeRef, productName: productName, configScreenUrl: configScreenUrl, onValidityChange: (v) => setIframeValid(v), onSuggestName: handleSuggestName })) : (_jsxs("p", { className: "text-xs text-zinc-500", children: ["Product manifest does not declare ", _jsx("code", { children: "ui.configScreenUrl" }), " \u2014 nothing to configure."] })), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { type: "button", variant: "primary", disabled: !canSubmit, onClick: handleSaveAndLaunch, children: submitting ? "Working…" : "Save & Launch…" }), _jsx(Button, { type: "submit", variant: "default", disabled: !canSubmit, children: "Save" }), _jsx(Button, { type: "button", variant: "ghost", onClick: onClose, children: "Cancel" })] })] })] }));
+}

package/components/index.d.ts

@@ -0,0 +1,3 @@
+export { ProductIframe, type ProductIframeHandle, type SubmitResult } from "./ProductIframe.js";
+export { ProductTemplateBuildForm, type ProductTemplateBuildOutcome, type ProductTemplateBuildRequest, } from "./ProductTemplateBuildForm.js";
+export { type ButtonProps, type ButtonSize, type ButtonVariant, type InputProps, type LabelProps, type UIPrimitives, UIPrimitivesProvider, useUIPrimitives, } from "./ui-primitives.js";

package/components/index.js

@@ -0,0 +1,3 @@
+export { ProductIframe } from "./ProductIframe.js";
+export { ProductTemplateBuildForm, } from "./ProductTemplateBuildForm.js";
+export { UIPrimitivesProvider, useUIPrimitives, } from "./ui-primitives.js";

package/components/ui-primitives.d.ts

@@ -0,0 +1,22 @@
+import { type ButtonHTMLAttributes, type ComponentType, type InputHTMLAttributes, type ReactNode } from "react";
+export type ButtonVariant = "default" | "ghost" | "danger" | "primary";
+export type ButtonSize = "xs" | "sm" | "md";
+export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+};
+export type InputProps = InputHTMLAttributes<HTMLInputElement>;
+export type LabelProps = {
+    children: ReactNode;
+    className?: string;
+};
+export interface UIPrimitives {
+    Button: ComponentType<ButtonProps>;
+    Input: ComponentType<InputProps>;
+    Label: ComponentType<LabelProps>;
+}
+export declare function UIPrimitivesProvider({ value, children }: {
+    value: UIPrimitives;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useUIPrimitives(): UIPrimitives;

package/components/ui-primitives.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, } from "react";
+const UIPrimitivesContext = createContext(null);
+export function UIPrimitivesProvider({ value, children }) {
+    return _jsx(UIPrimitivesContext.Provider, { value: value, children: children });
+}
+export function useUIPrimitives() {
+    const ctx = useContext(UIPrimitivesContext);
+    if (!ctx) {
+        throw new Error("useUIPrimitives: no UIPrimitivesProvider in tree. Wrap your app root with <UIPrimitivesProvider value={...}>.");
+    }
+    return ctx;
+}

package/dev-url.d.ts

@@ -0,0 +1 @@
+export declare function validateDevUrl(url: string): URL;

package/dev-url.js

@@ -0,0 +1,14 @@
+import { ProductError } from "./product-error.js";
+export function validateDevUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new ProductError("DEV_URL_INVALID", `dev URL is not a valid URL: ${url}`);
+    }
+    if (parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1") {
+        throw new ProductError("DEV_URL_NOT_LOCALHOST", `dev URL must be localhost or 127.0.0.1 (v1), got ${parsed.hostname}`);
+    }
+    return parsed;
+}

package/docker-runner.d.ts

@@ -0,0 +1,20 @@
+/** Role label stamped on every product control-plane container. The daemon's
+ *  infrastructure view discovers managed singletons by the presence of a
+ *  `norsk-ctl.role` label (proxy, proxy-oauth2, cpu-monitor, product); the
+ *  value doubles as the card's component name. */
+export declare const PRODUCT_ROLE_LABEL = "norsk-ctl.role=product";
+/** argv (sans leading "docker") that launches a product container: detached,
+ *  auto-removed, loopback-published to its internal 4321, and role-labelled so
+ *  it shows up in the Infrastructure tab. */
+export declare function productRunArgs(image: string, hostPort: number): string[];
+/** Stable container name for a product, derived from its manifest name, so
+ *  `docker ps` shows `norsk-product-studio` instead of a random docker alias.
+ *  Mirrors the singleton naming of norsk-proxy / norsk-ctl-cpu-monitor. */
+export declare function productContainerName(productName: string): string;
+export declare function dockerRun(image: string, hostPort: number): Promise<string>;
+export declare function dockerRm(containerId: string): Promise<void>;
+/** Best-effort rename of a running container. The product is tracked by
+ *  container id, never by name, so a rename failure (e.g. a stale container
+ *  already holding the name) is non-fatal — the product still works, it just
+ *  keeps its random docker alias. */
+export declare function dockerRename(containerId: string, name: string): Promise<void>;

package/docker-runner.js

@@ -0,0 +1,54 @@
+import { ProductError } from "./product-error.js";
+const CONTAINER_INTERNAL_PORT = 4321;
+/** Role label stamped on every product control-plane container. The daemon's
+ *  infrastructure view discovers managed singletons by the presence of a
+ *  `norsk-ctl.role` label (proxy, proxy-oauth2, cpu-monitor, product); the
+ *  value doubles as the card's component name. */
+export const PRODUCT_ROLE_LABEL = "norsk-ctl.role=product";
+/** argv (sans leading "docker") that launches a product container: detached,
+ *  auto-removed, loopback-published to its internal 4321, and role-labelled so
+ *  it shows up in the Infrastructure tab. */
+export function productRunArgs(image, hostPort) {
+    return [
+        "run",
+        "-d",
+        "--rm",
+        "--label",
+        PRODUCT_ROLE_LABEL,
+        "-p",
+        `127.0.0.1:${hostPort}:${CONTAINER_INTERNAL_PORT}`,
+        image,
+    ];
+}
+/** Stable container name for a product, derived from its manifest name, so
+ *  `docker ps` shows `norsk-product-studio` instead of a random docker alias.
+ *  Mirrors the singleton naming of norsk-proxy / norsk-ctl-cpu-monitor. */
+export function productContainerName(productName) {
+    const slug = productName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return `norsk-product-${slug || "unnamed"}`;
+}
+export async function dockerRun(image, hostPort) {
+    const proc = Bun.spawn(["docker", ...productRunArgs(image, hostPort)], { stdout: "pipe", stderr: "pipe" });
+    const exitCode = await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    if (exitCode !== 0 || !stdout) {
+        throw new ProductError("DOCKER_RUN_FAILED", `docker run failed (exit ${exitCode}): ${stderr || "no stderr"}`);
+    }
+    return stdout;
+}
+export async function dockerRm(containerId) {
+    const proc = Bun.spawn(["docker", "rm", "-f", containerId], { stdout: "pipe", stderr: "pipe" });
+    await proc.exited;
+}
+/** Best-effort rename of a running container. The product is tracked by
+ *  container id, never by name, so a rename failure (e.g. a stale container
+ *  already holding the name) is non-fatal — the product still works, it just
+ *  keeps its random docker alias. */
+export async function dockerRename(containerId, name) {
+    const proc = Bun.spawn(["docker", "rename", containerId, name], { stdout: "pipe", stderr: "pipe" });
+    await proc.exited;
+}