@norskvideo/ctl-dev-kit 0.1.97 → 0.1.98

package/create-product/{backend-turnkey.ts → turnkey.ts}

@@ -1,26 +1,151 @@
-// The backend-only turnkey shape (reuters-shaped): shared/ + backend/ + tests/,
-// no frontend, dashboards, or components workspace. Smallest product surface —
-// one composed workflow served as a product-template tar from an express
-// backend. The skeleton ships the post-review state as defaults: seed through
+// The turnkey skeleton — ONE module for every turnkey shape. The base emitted
+// here is reuters-shaped (shared/ + backend/ + tests/: one composed workflow
+// served as a product-template tar from an express backend); the components,
+// views, dashboard and frontend FEATURES add their workspaces on top and patch
+// the handful of shared files that have to know about them (see features/).
+//
+// There is deliberately no second copy of this skeleton per shape: it is ~1600
+// lines, the shape layer is not drift-gated, and three copies would diverge
+// within a release. A shape is a preset over features (create-product.ts).
+//
+// The skeleton ships the post-review state as defaults: seed through
 // parseManifestSeed, ManifestInput with no boilerplate, packProductTemplate
 // from the schema package, addComponent/stubbedLibrary with a THROWING
 // validate(), INVARIANTS + parity + byte-snapshot + studio-load wired into
 // test:unit, and an image smoke tier.
-import type { GeneratedFile, ShapeContext, ShapeModule } from "./create-product.ts";
+import { type GeneratedFile, type ShapeContext, type ShapeModule, studioPackage } from "./create-product.ts";
+import {
+  COMPONENTS_GITIGNORE,
+  componentsFiles,
+  EXAMPLE_ID,
+  EXAMPLE_IDENTIFIER,
+  libraryPackage,
+} from "./features/components.ts";
+import {
+  DASHBOARD_GITIGNORE,
+  DASHBOARD_PROXY_EXPOSE,
+  DASHBOARD_RUNTIME_SCREEN,
+  dashboardFiles,
+} from "./features/dashboard.ts";
+import { CONFIG_SCREEN_URL, FRONTEND_SERVER_BLOCK, frontendFiles } from "./features/frontend.ts";
+import { VIEWS_PROXY_EXPOSE, VIEWS_RUNTIME_SCREEN, viewsFiles } from "./features/views.ts";
+
+// The per-feature section of the generated CLAUDE.md: what each optional
+// workspace is, and the trap that comes with it. Every line here is something
+// a fleet review found someone had to rediscover.
+function featureNotes(ctx: ShapeContext): string {
+  const sections: string[] = [];
+  if (ctx.features.has("components")) {
+    sections.push(`### \`components/\` — this product's own Studio nodes
+
+Build order is load-bearing: \`codegen\` (types.source.yaml -> _gen/types.ts)
+-> \`tsc\` -> \`copy-yamls\` (types.yaml beside the compiled runtime, plus the
+BROWSER bundle info.client.js). \`bun run build:components\` does all three.
+
+It is CommonJS on purpose (\`module: "commonjs"\`): under \`node16\` Node's
+CJS-via-ESM interop double-wraps the exports object and \`infoMod.default\`
+becomes the wrapper rather than the component factory.
+
+Adding a component is dropping a sibling directory under
+\`components/src/library/\` with an \`info.ts\` and a \`runtime.ts\` — the library
+entry discovers it. But TWO things elsewhere have to follow, and both fail
+quietly:
+
+- **\`COMPONENT_STUBS\`** (\`shared/src/workflow/studio-library.ts\`) — the
+  builder's library is Studio's npm NodeInfos, which cannot know this product's
+  own nodes. Without a stub the composer's throwing \`validate()\` rejects the
+  graph. Declare the stub; never demote \`validate()\` to a warning.
+- **\`server.library\` in the emitted compose** — the product's list OVERRIDES
+  the daemon's seeded \`default.yaml\` rather than merging, so it must name every
+  library including the built-ins. A component that is mounted but missing here
+  is never loaded, with no error at all.
+
+\`components/src/library/example/\` is a placeholder wired all the way through so
+a fresh repo proves the pipeline on its first launch. Replace it or delete it.
+`);
+  }
+  if (ctx.features.has("views")) {
+    sections.push(`### The operator screen — component views
+
+\`summary.tsx\` / \`fullscreen.tsx\` beside the component, registered under its
+\`runtime\` and rendered INSIDE Studio's workflow view. State arrives as
+\`ViewProps.state\` (pushed from every \`updates.update()\`) and commands leave
+through \`sendCommand\` — a view never fetches and never opens a socket.
+
+They are bundled for the BROWSER by \`copy-yamls\`, and Studio's loader has no
+import map: a bare specifier left in info.client.js is a fatal
+module-resolution crash in the workflow view. React is rewritten to Studio's
+window globals so no second copy is bundled;
+\`components/src/library/info-client-externals.test.ts\` guards it.
+
+The template manifest points \`runtimeScreenUrl\` at Studio's own \`/studio/\`
+route, and \`proxy.expose\` carries \`/live/*\` — \`/live/api/*\` alone covers the
+component's routes but not its PAGES or their state websockets.
+`);
+  }
+  if (ctx.features.has("dashboard")) {
+    sections.push(`### The operator screen — dashboard SPA
+
+Four paths name the same thing, and conflating them is how a dashboard builds,
+packs and launches while serving a 404:
+
+| Layer                | Path                                    |
+| -------------------- | --------------------------------------- |
+| repo (vite outDir)   | \`dashboards/workflow/\`                 |
+| inside the tar       | \`dashboards/workflow/\`                 |
+| inside the container | \`studio-save-files/workflow/dashboards/\` |
+| URL                  | \`/dashboard/workflow/\`                 |
+
+The directory name **is** the workflow name. The tar ships \`workflow.yml\` at
+its root, so the workflow is \`workflow\`; ctl does the rename at mount.
+
+\`base: "./"\` is required — the page is served behind a per-instance proxy
+prefix, so absolute asset URLs escape it. And the API client discovers
+\`apiBasePath\`/\`wsBasePath\` from the \`env\` document Studio serves beside the
+page: a root-absolute \`/live/api/...\` resolves against the PROXY ROOT and never
+reaches the instance.
+
+\`proxy.expose\` carries \`/dashboard/*\`. Without it the dashboard works on the
+direct Studio port and 404s through the proxy.
+`);
+  }
+  if (ctx.features.has("frontend")) {
+    sections.push(`### \`frontend/\` — the configure screen
+
+Served by THIS container at \`/configure\` and iframed by ctl at
+\`manifest.ui.configScreenUrl\`. Not an operator screen: that is per-instance and
+Studio's, this is registration-time and ours.
+
+The daemon PROBES \`configScreenUrl\` at \`product add\` and refuses the product
+with \`CONFIG_SCREEN_UNREACHABLE\` if it does not answer. The backend serves
+\`frontend/dist\`, so it must be built first — \`bun run dev\` and the image build
+both do. \`bun run dev:frontend\` is vite's own server, for iterating on the
+screen with HMR.
+`);
+  }
+  if (sections.length === 0) return "";
+  return `## The optional workspaces this repo has
+
+${sections.join("\n")}
+`;
+}
 
 function claudeHead(ctx: ShapeContext): string {
+  const features = [...ctx.features].sort();
+  const built = features.length === 0 ? "no optional workspaces" : `features: ${features.join(", ")}`;
   return `# Working in this repo (${ctx.name})
 
 This is a **standalone product repo** generated by \`ctl-dev-kit create-product\`
-(shape: backend-turnkey). It builds a backend-only product container image and
-launches through the **released** norsk-ctl daemon — it needs no norsk-ctl
-source checkout. This file is conventions + gotchas; the fenced block below is
-the drift-gated shared core.
+(${built}). It builds a product container image and launches through the
+**released** norsk-ctl daemon — it needs no norsk-ctl source checkout. This
+file is conventions + gotchas; the fenced block below is the drift-gated
+shared core.
 `;
 }
 
 function claudeTail(ctx: ShapeContext): string {
-  return `## Getting norsk-ctl + the dev loop
+  const workspaceNotes = featureNotes(ctx);
+  return `${workspaceNotes}## Getting norsk-ctl + the dev loop
 
 \`norsk-ctl\` (the daemon/CLI) is **not** an npm dep — it's the released binary,
 pinned in \`flake.nix\` and put on PATH by the nix shell:
@@ -47,12 +172,18 @@ fresh image and checks the pins before relaunching.
 
 ## First run after generation
 
-1. \`bun install\`
-2. \`UPDATE_SNAPSHOTS=1 bun run test:unit\` — bakes the byte-snapshot fixtures
-   under \`tests/unit/__snapshots__/\` (the generator cannot compose without the
-   Studio packages installed). Commit them; from then on any emission change is
-   a reviewable fixture diff.
-3. \`bun run check:drift && bun run docs:check && bun run test:unit && bun run typecheck\`
+1. \`nix develop\` — the dev shell: pinned bun, biome and norsk-ctl.
+2. \`git init && bun install\`
+3. \`UPDATE_SNAPSHOTS=1 bun run test:unit\` — bakes the byte-snapshot fixtures
+   under tests/unit/__snapshots__/ (the generator cannot compose without the
+   Studio packages installed). That directory does not exist until this command
+   creates it, which is why it is not written as a repo path here. Commit the
+   fixtures; from then on any emission change is a reviewable fixture diff.
+4. \`bun run check:drift && bun run docs:check && bun run test:unit && bun run typecheck && bun run lint\`
+5. Replace the starter graph in \`shared/src/workflow/\` with the real one,
+   keeping \`INVARIANTS.md\` and its rules tests in step.
+6. \`bun run docs:handover\` — once a daemon has this product added; fills the
+   handover's generated block from the launch truth.
 
 ## Version pins
 
@@ -108,20 +239,31 @@ bytes; \`UPDATE_SNAPSHOTS=1\` refreshes deliberately.
 
 function rootPackageJson(ctx: ShapeContext): string {
   const { studioLib, mediaLib } = ctx.pins;
+  const hasComponents = ctx.features.has("components");
+  const hasDashboard = ctx.features.has("dashboard");
+  const hasFrontend = ctx.features.has("frontend");
   return `${JSON.stringify(
     {
       name: ctx.name,
       version: "0.0.1",
       private: true,
       type: "module",
-      workspaces: ["shared", "backend", "tests"],
+      workspaces: [
+        "shared",
+        ...(hasComponents ? ["components"] : []),
+        ...(hasDashboard ? ["dashboard"] : []),
+        ...(hasFrontend ? ["frontend"] : []),
+        "backend",
+        "tests",
+      ],
       scripts: {
+        ...(hasComponents ? { codegen: "bun run --cwd components codegen" } : {}),
         clean: "bun run --cwd shared clean",
         format: "biome format --write .",
         lint: "biome check .",
         "lint:fix": "biome check --write .",
         test: "bun run test:unit",
-        "test:unit": "bun test shared/src/ backend/src/ tests/unit/",
+        "test:unit": `bun test shared/src/ backend/src/ ${hasComponents ? "components/src/ " : ""}tests/unit/`,
         "test:image": "bun test tests/image/",
         "check:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/check-drift.ts",
         "docs:check": "bun run node_modules/@norskvideo/ctl-dev-kit/docs/path-existence.ts",
@@ -129,13 +271,37 @@ function rootPackageJson(ctx: ShapeContext): string {
         "docs:handover": "bash scripts/docs-handover.sh",
         "docs:handover:check": "bash scripts/docs-handover.sh --check",
         "sync:drift": "bun run node_modules/@norskvideo/ctl-dev-kit/conventions/sync-drift.ts",
-        typecheck: "bunx tsc --noEmit -p shared && bunx tsc --noEmit -p backend && bunx tsc --noEmit -p .",
+        // codegen first: components/_gen/types.ts is gitignored build output,
+        // so on a clean checkout tsc has nothing to resolve against without it.
+        typecheck: [
+          ...(hasComponents ? ["bun run codegen"] : []),
+          "bunx tsc --noEmit -p shared",
+          ...(hasComponents ? ["bunx tsc --noEmit -p components"] : []),
+          ...(hasDashboard ? ["bunx tsc --noEmit -p dashboard"] : []),
+          ...(hasFrontend ? ["bunx tsc --noEmit -p frontend"] : []),
+          "bunx tsc --noEmit -p backend",
+          "bunx tsc --noEmit -p .",
+        ].join(" && "),
         build: "bun run lint && bun run typecheck && bun run build:no-lint",
-        "build:no-lint": "bun run build:shared && bun run build:backend && bun run docs:manual",
+        "build:no-lint": [
+          "bun run build:shared",
+          ...(hasComponents ? ["bun run build:components"] : []),
+          ...(hasDashboard ? ["bun run build:dashboard"] : []),
+          ...(hasFrontend ? ["bun run build:frontend"] : []),
+          "bun run build:backend",
+          "bun run docs:manual",
+        ].join(" && "),
         "build:shared": "bun run --cwd shared build",
+        ...(hasComponents ? { "build:components": "bun run --cwd components build" } : {}),
+        ...(hasDashboard ? { "build:dashboard": "bun run --cwd dashboard build" } : {}),
+        ...(hasFrontend ? { "build:frontend": "bun run --cwd frontend build" } : {}),
         "build:backend": "bun run --cwd backend build",
         "build:image": "bash deployment/build-image.sh",
-        dev: "bun run --cwd backend dev",
+        // The backend SERVES frontend/dist, so a dev loop that never builds it
+        // hands the daemon's configure-screen probe a 404. `dev:frontend` is
+        // vite's own server, for iterating on the screen with HMR.
+        dev: hasFrontend ? "bun run build:frontend && bun run --cwd backend dev" : "bun run --cwd backend dev",
+        ...(hasFrontend ? { "dev:frontend": "bun run --cwd frontend dev" } : {}),
         start: "bun run --cwd backend start",
         iterate: "bash deployment/iterate.sh",
         demo: "ctl-demo",
@@ -159,6 +325,7 @@ function rootPackageJson(ctx: ShapeContext): string {
         "@norskvideo/norsk-api": mediaLib,
         "@norskvideo/norsk-sdk": mediaLib,
         "@norskvideo/norsk-studio": studioLib,
+        ...optionalStudioPins(ctx),
         "@norskvideo/norsk-studio-builder": studioLib,
         "@norskvideo/norsk-studio-built-ins": studioLib,
       },
@@ -168,6 +335,10 @@ function rootPackageJson(ctx: ShapeContext): string {
   )}\n`;
 }
 
+function optionalStudioPins(ctx: ShapeContext): Record<string, string> {
+  return Object.fromEntries(ctx.studioLibs.map((lib) => [studioPackage(lib), ctx.pins.studioLib]));
+}
+
 function invariantsMd(ctx: ShapeContext): string {
   return `# Workflow invariants
 
@@ -208,8 +379,11 @@ function sharedPackageJson(ctx: ShapeContext): string {
         "./workflow": "./src/workflow/index.ts",
       },
       scripts: {
-        build:
-          "bun build src/index.ts --outdir dist --target=bun --external @norskvideo/norsk-studio --external @norskvideo/norsk-studio-builder --external @norskvideo/norsk-studio-built-ins",
+        build: [
+          "bun build src/index.ts --outdir dist --target=bun --external @norskvideo/norsk-studio",
+          ...ctx.studioLibs.map((lib) => `--external ${studioPackage(lib)}`),
+          "--external @norskvideo/norsk-studio-builder --external @norskvideo/norsk-studio-built-ins",
+        ].join(" "),
         clean: "rm -rf dist",
         test: "bun test src/",
         typecheck: "bunx tsc --noEmit",
@@ -219,6 +393,7 @@ function sharedPackageJson(ctx: ShapeContext): string {
         "@norskvideo/ctl-sdk": "^0.1.1",
         "@norskvideo/norsk-sdk": mediaLib,
         "@norskvideo/norsk-studio": studioLib,
+        ...optionalStudioPins(ctx),
         "@norskvideo/norsk-studio-builder": studioLib,
         "@norskvideo/norsk-studio-built-ins": studioLib,
         yaml: "^2.8.0",
@@ -335,16 +510,14 @@ it("repo and tag recombine to the full image ref", () => {
 `;
 }
 
-const MANIFEST_TS = `import { type Manifest, type ManifestInput, ManifestSchema } from "@norskvideo/ctl-sdk/browser";
+const MANIFEST_TS_TEMPLATE = `import { type Manifest, type ManifestInput, ManifestSchema } from "@norskvideo/ctl-sdk/browser";
 import { PRODUCT_NAME, PRODUCT_VERSION } from "./version.ts";
 
 // Producer-side ManifestInput: everything the schema defaults stays omitted
-// (cli/components/runtime), so this declares only what the product has. A
-// backend-only turnkey has no configure UI — configScreenUrl is optional and
-// omitted, so the runner skips its registration probe (no placeholder HTML);
-// its one ui entry is the documentation the image serves at /docs.
+// (cli/components/runtime), so this declares only what the product has.
 // Parsing at build time keeps the served manifest the READER shape with the
 // defaults filled in.
+__CONFIG_SCREEN_NOTE__
 export function buildManifest(): Manifest {
   const manifest: ManifestInput = {
     manifestSchemaVersion: 1,
@@ -353,19 +526,38 @@ export function buildManifest(): Manifest {
     minRunnerVersion: "0.1.0",
     api: {
       basePath: "/api",
-      proxyPaths: ["/api/*"],
+      proxyPaths: [__PROXY_PATHS__],
       openapiFragmentPath: "/api/openapi.yaml",
     },
     targets: ["docker-compose"],
     // Keep in lockstep with STARTER_CONFIGS in backend/src/routes/product-template.ts.
     defaultProductTemplates: [{ name: "default", url: "/api/product-template/default" }],
-    ui: { sidebarEntries: [{ label: "Documentation", route: "/docs/" }] },
+    ui: { __CONFIG_SCREEN__sidebarEntries: [{ label: "Documentation", route: "/docs/" }] },
   };
   return ManifestSchema.parse(manifest);
 }
 `;
 
-const MANIFEST_TEST_TS = `import { describe, expect, it } from "bun:test";
+function manifestTs(ctx: ShapeContext): string {
+  const hasFrontend = ctx.features.has("frontend");
+  return MANIFEST_TS_TEMPLATE.replace(
+    "__CONFIG_SCREEN_NOTE__",
+    hasFrontend
+      ? `// The configure screen is served by THIS container out of frontend/dist. The
+// daemon probes it at \`product add\` and refuses the product with
+// CONFIG_SCREEN_UNREACHABLE if it does not answer, so it must be built first.`
+      : `// This product has no configure UI — configScreenUrl is optional and omitted,
+// so the daemon skips its registration probe entirely (no placeholder HTML
+// needed); the one ui entry is the documentation the image serves at /docs.`,
+  )
+    .replace(
+      "__PROXY_PATHS__",
+      ['"/api/*"', ...(hasFrontend ? [`"${CONFIG_SCREEN_URL}"`, `"${CONFIG_SCREEN_URL}/*"`] : [])].join(", "),
+    )
+    .replace("__CONFIG_SCREEN__", hasFrontend ? `configScreenUrl: "${CONFIG_SCREEN_URL}", ` : "");
+}
+
+const MANIFEST_TEST_TS_TEMPLATE = `import { describe, expect, it } from "bun:test";
 import { ManifestSchema } from "@norskvideo/ctl-sdk/browser";
 import { buildManifest } from "./manifest.ts";
 
@@ -374,11 +566,25 @@ describe("manifest", () => {
     expect(ManifestSchema.safeParse(buildManifest()).success).toBe(true);
   });
 
-  it("omits the configure UI (backend-only: the runner skips its probe)", () => {
+__CONFIG_SCREEN_TEST__});
+`;
+
+function manifestTestTs(ctx: ShapeContext): string {
+  return MANIFEST_TEST_TS_TEMPLATE.replace(
+    "__CONFIG_SCREEN_TEST__",
+    ctx.features.has("frontend")
+      ? `  it("declares the configure screen and proxies it", () => {
+    const manifest = buildManifest();
+    expect(manifest.ui.configScreenUrl).toBe("${CONFIG_SCREEN_URL}");
+    expect(manifest.api.proxyPaths).toContain("${CONFIG_SCREEN_URL}");
+  });
+`
+      : `  it("omits the configure UI (the daemon then skips its probe)", () => {
     expect(buildManifest().ui.configScreenUrl).toBeUndefined();
   });
-});
-`;
+`,
+  );
+}
 
 const SCHEMAS_INDEX_TS = `export * from "./config.ts";
 `;
@@ -428,13 +634,20 @@ describe("ProductConfigSchema", () => {
 });
 `;
 
-const IDS_TS = `// Stable component ids — part of the workflow contract: they appear in the
+const IDS_TS_TEMPLATE = `// Stable component ids — part of the workflow contract: they appear in the
 // emitted YAML and are cited by INVARIANTS.md rules, so never rename without
 // coordinating every consumer.
 export const INGEST_ID = "ingest";
 export const EGEST_ID = "egest";
 export const PREVIEW_ID = "preview";
-`;
+__EXAMPLE_ID__`;
+
+function idsTs(ctx: ShapeContext): string {
+  return IDS_TS_TEMPLATE.replace(
+    "__EXAMPLE_ID__",
+    ctx.features.has("components") ? `export const EXAMPLE_ID = "${EXAMPLE_ID}";\n` : "",
+  );
+}
 
 const COMPONENTS_TS = `// Typed factories for the Studio components the starter graph wires up.
 // Config types come from each built-in's OpenAPI-generated _gen/types, so
@@ -527,7 +740,7 @@ export function preview(args: PreviewArgs): WorkflowComponent<PreviewConfig> {
 }
 `;
 
-const STUDIO_LIBRARY_TS = `// Build the composer's ComponentLibrary: Studio's REAL NodeInfos first, this
+const STUDIO_LIBRARY_TS_TEMPLATE = `// Build the composer's ComponentLibrary: Studio's REAL NodeInfos first, this
 // product's declared stubs second, and nothing else — so builder.validate()
 // stays a THROWING gate (a typo'd identifier fails the compose instead of
 // silently resolving to a permissive synthetic).
@@ -540,7 +753,7 @@ const STUDIO_LIBRARY_TS = `// Build the composer's ComponentLibrary: Studio's RE
 import { callableDefault } from "@norskvideo/ctl-sdk";
 import { type ComponentStubSpec, stubbedLibrary } from "@norskvideo/ctl-sdk/workflow";
 import { RegistrationConsts } from "@norskvideo/norsk-studio/lib/extension/client-types";
-import type { ComponentLibrary, NodeInfoForBuilder } from "@norskvideo/norsk-studio-builder";
+__OPTIONAL_IMPORTS__import type { ComponentLibrary, NodeInfoForBuilder } from "@norskvideo/norsk-studio-builder";
 import getNodeInfoImport from "@norskvideo/norsk-studio-built-ins/lib/info";
 
 // TS-compiled-to-CJS with __esModule + exports.default; how that surfaces to
@@ -550,22 +763,53 @@ const getNodeInfo = callableDefault<(consts: unknown, identifier: string) => unk
   getNodeInfoImport,
   "@norskvideo/norsk-studio-built-ins/lib/info",
 );
-
-// Components not in the npm library (this product's own, or alpha/custom nodes
-// that live only in the studio image) are declared here as metadata-only stubs
-// — precise media contracts, no browser code, no _gen/types needed. See
-// ComponentStubSpec in @norskvideo/ctl-sdk/workflow.
-export const COMPONENT_STUBS: ComponentStubSpec[] = [];
+__OPTIONAL_LOOKUPS__
+// Components no npm library provides (this product's own) are declared here as
+// metadata-only stubs — precise media contracts, no browser code, no _gen/types
+// needed. Studio's alpha/beta components come from --studio-libs instead, so
+// their configs stay typed. See ComponentStubSpec in @norskvideo/ctl-sdk/workflow.
+export const COMPONENT_STUBS: ComponentStubSpec[] = [__STUBS__];
+
+// Each library's aggregator returns undefined for an identifier it does not own.
+const LOOKUPS = [__LOOKUPS__];
+
+function findNodeInfo(identifier: string): NodeInfoForBuilder | undefined {
+  for (const lookup of LOOKUPS) {
+    const info = lookup(RegistrationConsts, identifier);
+    if (info !== undefined) return info as NodeInfoForBuilder;
+  }
+  return undefined;
+}
 
 export async function buildStudioLibrary(): Promise<ComponentLibrary> {
-  return stubbedLibrary<NodeInfoForBuilder>(
-    (identifier) => getNodeInfo(RegistrationConsts, identifier) as NodeInfoForBuilder | undefined,
-    COMPONENT_STUBS,
-  );
+  return stubbedLibrary<NodeInfoForBuilder>(findNodeInfo, COMPONENT_STUBS);
 }
 `;
 
-const COMPOSE_WORKFLOW_TS = `// The production composer: source-first, left-to-right, every connect narrowed
+function studioLibraryTs(ctx: ShapeContext): string {
+  // The placeholder component is this product's own, so the builder's library
+  // (Studio's npm NodeInfos) cannot know it. Without the stub the composer's
+  // THROWING validate() rejects the starter graph — the trap that tempts people
+  // into demoting validate() to a warning.
+  const stubs = ctx.features.has("components")
+    ? `\n  // The placeholder component: a pure side-car, so no accepts/produces —\n  // mirrors \`subscription: {}\` in components/src/library/example/info.ts.\n  { identifier: "${EXAMPLE_IDENTIFIER}" },\n`
+    : "";
+  const libs = ctx.studioLibs;
+  const lookupName = (lib: string) => `get${lib[0]?.toUpperCase()}${lib.slice(1)}NodeInfo`;
+  const imports = libs.map((lib) => `import ${lib}InfoImport from "${studioPackage(lib)}/lib/info";\n`).join("");
+  const lookups = libs
+    .map(
+      (lib) =>
+        `const ${lookupName(lib)} = callableDefault<(consts: unknown, identifier: string) => unknown>(\n  ${lib}InfoImport,\n  "${studioPackage(lib)}/lib/info",\n);\n`,
+    )
+    .join("");
+  return STUDIO_LIBRARY_TS_TEMPLATE.replace("__STUBS__", stubs)
+    .replace("__OPTIONAL_IMPORTS__", imports)
+    .replace("__OPTIONAL_LOOKUPS__", lookups)
+    .replace("__LOOKUPS__", ["getNodeInfo", ...libs.map(lookupName)].join(", "));
+}
+
+const COMPOSE_WORKFLOW_TS_TEMPLATE = `// The production composer: source-first, left-to-right, every connect narrowed
 // through a pick* helper so filters resolve against real availableStreams().
 // addComponent keeps the factories' typing at the addNode boundary — no
 // \`config as never\`.
@@ -573,7 +817,7 @@ import { addComponent, toWorkflowDoc, type WorkflowDoc } from "@norskvideo/ctl-s
 import { autoLayout, type ComponentLibrary, pickAll, WorkflowBuilder } from "@norskvideo/norsk-studio-builder";
 import type { ProductConfig } from "../schemas/config.ts";
 import { egestSrtCaller, ingestSrtCaller, ingestSrtListener, preview } from "./components.ts";
-import { EGEST_ID, INGEST_ID, PREVIEW_ID } from "./ids.ts";
+__EXAMPLE_IMPORTS__import { EGEST_ID, INGEST_ID, PREVIEW_ID } from "./ids.ts";
 
 export function composeWorkflow(config: ProductConfig, library: ComponentLibrary): WorkflowDoc {
   const builder = new WorkflowBuilder(library);
@@ -610,7 +854,7 @@ export function composeWorkflow(config: ProductConfig, library: ComponentLibrary
 
   pickAll(builder.connect(ingest, egest), ["video", "audio"]);
   pickAll(builder.connect(ingest, monitor), ["video"]);
-
+__EXAMPLE_NODE__
   // Layer 2 is a THROWING gate (INV-COMPOSE-001). Never demote this to a
   // warning — declare out-of-library components in COMPONENT_STUBS instead.
   const issues = builder.validate();
@@ -625,6 +869,27 @@ export function composeWorkflow(config: ProductConfig, library: ComponentLibrary
 }
 `;
 
+function composeWorkflowTs(ctx: ShapeContext): string {
+  if (!ctx.features.has("components")) {
+    return COMPOSE_WORKFLOW_TS_TEMPLATE.replace("__EXAMPLE_IMPORTS__", "").replace("__EXAMPLE_NODE__", "");
+  }
+  return COMPOSE_WORKFLOW_TS_TEMPLATE.replace(
+    "__EXAMPLE_IMPORTS__",
+    'import { exampleSidecar } from "./example-config.ts";\n',
+  )
+    .replace(
+      "__EXAMPLE_NODE__",
+      `
+  // The placeholder component, wired in so a freshly generated product proves
+  // the whole custom-node pipeline on its first launch: registered, in the
+  // toolbox, publishing state. It carries no media (subscription: {}), so it
+  // connects to nothing and perturbs no edge. Delete it with the component.
+  addComponent(builder, exampleSidecar({ id: EXAMPLE_ID, displayName: "Example" }));
+`,
+    )
+    .replace("import { EGEST_ID, INGEST_ID, PREVIEW_ID }", "import { EGEST_ID, EXAMPLE_ID, INGEST_ID, PREVIEW_ID }");
+}
+
 const COMPOSE_WORKFLOW_TEST_TS = `// Layer 3: the INVARIANTS.md rules table in executable form. Each rule cites
 // its INV-* ID verbatim; tests/unit/invariants-parity.test.ts fails the suite
 // if table and tests drift apart. The matrix exercises every composer branch.
@@ -700,11 +965,16 @@ test("INV-COMPOSE-001: an identifier that is neither real nor stubbed fails the
 });
 `;
 
-const WORKFLOW_INDEX_TS = `export * from "./components.ts";
-export * from "./compose-workflow.ts";
-export * from "./ids.ts";
-export * from "./studio-library.ts";
-`;
+function workflowIndexTs(ctx: ShapeContext): string {
+  return [
+    'export * from "./components.ts";',
+    'export * from "./compose-workflow.ts";',
+    ...(ctx.features.has("components") ? ['export * from "./example-config.ts";'] : []),
+    'export * from "./ids.ts";',
+    'export * from "./studio-library.ts";',
+    "",
+  ].join("\n");
+}
 
 const SHARED_INDEX_TS = `export * from "./manifest.ts";
 export * from "./product-template.ts";
@@ -713,7 +983,77 @@ export * from "./version.ts";
 export * from "./workflow/index.ts";
 `;
 
+// Biome collapses an array onto one line whenever it fits the 120-column width
+// and breaks it one element per line otherwise; objects keep the expansion they
+// are written with. An emitted array whose length depends on the product name
+// has to be laid out by the same rule, or the generated repo fails lint.
+function biomeStringArray(prefix: string, suffix: string, items: string[]): string {
+  const quoted = items.map((item) => `"${item}"`);
+  const oneLine = `${prefix}[${quoted.join(", ")}]${suffix}`;
+  if (oneLine.length <= 120) return oneLine;
+  const indent = `${prefix.match(/^ */)?.[0] ?? ""}  `;
+  return `${prefix}[\n${quoted.map((q) => `${indent}${q},`).join("\n")}\n${indent.slice(2)}]${suffix}`;
+}
+
 function productTemplateTs(ctx: ShapeContext): string {
+  const hasComponents = ctx.features.has("components");
+  // The shared module stays I/O-free: callers (the backend route, tests) read
+  // from disk and hand the bytes in.
+  const optsFields = [
+    ...(hasComponents
+      ? [
+          `  // Pre-read component files (components/lib, compiled).
+  components?: Array<{ path: string; content: string | Uint8Array<ArrayBuffer> }>;`,
+        ]
+      : []),
+    ...(ctx.features.has("dashboard")
+      ? [
+          `  // Pre-read dashboard files, keyed by workflow name (dashboards/, built).
+  dashboards?: Array<{ path: string; content: string | Uint8Array<ArrayBuffer> }>;`,
+        ]
+      : []),
+  ]
+    .map((field) => `${field}\n`)
+    .join("");
+  const materialComponents = hasComponents ? "opts.components ?? []" : "[]";
+  const materialDashboards = ctx.features.has("dashboard") ? "opts.dashboards ?? []" : "[]";
+  const studioLibraries = biomeStringArray("        library: ", ",", [
+    "@norskvideo/norsk-studio-built-ins",
+    ...ctx.studioLibs.map(studioPackage),
+    ...(hasComponents ? [libraryPackage(ctx)] : []),
+  ]);
+  // Where the operator looks. Each feature answers it differently, and the
+  // proxy entry it needs comes with it — a screen exposed on the wrong path
+  // works on the direct port and 404s through the proxy.
+  const screen = ctx.features.has("views")
+    ? VIEWS_RUNTIME_SCREEN
+    : ctx.features.has("dashboard")
+      ? DASHBOARD_RUNTIME_SCREEN
+      : undefined;
+  const screenWhy = ctx.features.has("views")
+    ? `      // The whole per-instance surface is Studio's: ctl anchors
+      // studio_url_prefix on its own /studio/ route, so the component's
+      // fullscreen page resolves under it.`
+    : `      // Studio's per-workflow mount serves the dashboards/ directory the
+      // template packs. The path segment IS the workflow name — the tar ships
+      // workflow.yml at its root, so it is "workflow".`;
+  const runtimeScreen = screen
+    ? `    ui: {
+${screenWhy}
+      runtimeScreenUrl: "${screen.url}",
+      runtimeScreenLabel: "${screen.label}",
+    },\n`
+    : "";
+  const proxyExpose = [
+    '"/"',
+    '"/static/*"',
+    '"/api/*"',
+    ...(ctx.features.has("views") ? [`"${VIEWS_PROXY_EXPOSE}"`] : []),
+    ...(ctx.features.has("dashboard") ? [`"${DASHBOARD_PROXY_EXPOSE}"`] : []),
+    '"/live/api/*"',
+    '"/ws"',
+    '"/ws/*"',
+  ].join(", ");
   return `// Product-template materials: the manifest/compose/parameters/workflow set the
 // runner stores at \`product add\`. Packing to tar is single-sourced in
 // @norskvideo/ctl-product-template-schema/pack — this repo carries no copy of
@@ -739,16 +1079,14 @@ export type BuildOpts = {
   // Create-time custom defaults from the build form's disclosure, merged
   // per-knob over STANDARD_ADVANCED_OVERRIDES into manifest.advanced.
   advanced?: ProductTemplateManifest["advanced"];
-};
+${optsFields}};
 
 // The build form rides its Custom defaults as a reserved $advancedDefaults
 // sibling of the config keys; the config schema is strict, so split it off
 // before the parse. Absent key = plain config passthrough.
 export function splitAdvancedDefaults(
   body: unknown,
-):
-  | { ok: true; config: unknown; advanced?: ProductTemplateManifest["advanced"] }
-  | { ok: false; issues: unknown[] } {
+): { ok: true; config: unknown; advanced?: ProductTemplateManifest["advanced"] } | { ok: false; issues: unknown[] } {
   if (typeof body !== "object" || body === null || !("$advancedDefaults" in body)) return { ok: true, config: body };
   const { $advancedDefaults: raw, ...config } = body as Record<string, unknown>;
   const parsed = ProductTemplateAdvancedSchema.safeParse(raw);
@@ -771,10 +1109,10 @@ export function buildProductTemplateMaterials(config: ProductConfig, opts: Build
     productVersion: PRODUCT_VERSION,
     target: "docker-compose",
     generatedAt: generatedAt.toISOString(),
-    proxy: {
+${runtimeScreen}    proxy: {
       // Permissive starter set: exposes Studio's own UI/API through the oauth2
       // proxy. Narrow as the product grows a surface of its own.
-      expose: ["/", "/static/*", "/api/*", "/live/api/*", "/ws", "/ws/*"],
+      expose: [${proxyExpose}],
     },
     advanced: { ...STANDARD_ADVANCED_OVERRIDES, ...opts.advanced },
   };
@@ -784,8 +1122,8 @@ export function buildProductTemplateMaterials(config: ProductConfig, opts: Build
     composeYaml: renderCompose(config),
     parameters: { parameters: renderParameters(config) },
     workflow: yamlStringify(composeWorkflow(config, opts.library), { aliasDuplicateObjects: false }),
-    components: [],
-    dashboards: [],
+    components: ${materialComponents},
+    dashboards: ${materialDashboards},
     assets: [],
     workdirSeed: [],
   };
@@ -801,7 +1139,14 @@ export function renderCompose(config: ProductConfig): string {
     // without it Studio falls back to its baked default and the instance would
     // demand a Studio entitlement rather than its own.
     NORSK_PRODUCT_NAME: PRODUCT_NAME,
-    NODE_CONFIG: JSON.stringify({ server: { library: ["@norskvideo/norsk-studio-built-ins"] } }),
+    // The product's list OVERRIDES the daemon's seeded default.yaml rather than
+    // merging with it, so it has to name EVERY library it wants loaded — a
+    // component mounted but absent from here is never loaded, with no error.
+    NODE_CONFIG: JSON.stringify({
+      server: {
+${studioLibraries}
+      },
+    }),
   };
 
   // biome-ignore lint/suspicious/noTemplateCurlyInString: docker-compose variable reference, not a TS template literal
@@ -968,15 +1313,23 @@ console.log(\`${ctx.name} listening on :\${port}\`);
 }
 
 function backendServerTs(ctx: ShapeContext): string {
+  const hasFrontend = ctx.features.has("frontend");
+  const frontendImports = hasFrontend ? 'import path from "node:path";\n' : "";
+  const frontendDist = hasFrontend
+    ? '\nconst FRONTEND_DIST = path.resolve(import.meta.dir, "../../frontend/dist");\n'
+    : "";
+  // Carries its own LEADING newline and no trailing one, so the absent case
+  // leaves exactly one blank line rather than two.
+  const frontendBlock = hasFrontend ? `\n${FRONTEND_SERVER_BLOCK}\n` : "";
   return `import type { Server } from "node:http";
-import { buildStudioLibrary } from "${ctx.scope}/shared/workflow";
+${frontendImports}import { buildStudioLibrary } from "${ctx.scope}/shared/workflow";
 import { docsBundleDir, serveDocs } from "@norskvideo/ctl-sdk";
 import cors from "cors";
 import express from "express";
 import { manifestRouter } from "./routes/manifest.ts";
 import { openapiRouter } from "./routes/openapi.ts";
 import { makeProductTemplateRouter } from "./routes/product-template.ts";
-
+${frontendDist}
 export async function startServer(port: number): Promise<Server> {
   // Built once at startup: Studio's real NodeInfos + this product's declared
   // stubs. Passed into the product-template route so every build reuses it.
@@ -996,7 +1349,7 @@ export async function startServer(port: number): Promise<Server> {
   // The docs bundle (\`bun run docs:manual\`, baked into the image as docs/),
   // served at /docs; a no-op until it has been built.
   serveDocs(app, docsBundleDir(import.meta.dir));
-
+${frontendBlock}
   return await new Promise<Server>((resolve, reject) => {
     const server = app.listen(port, () => resolve(server));
     server.on("error", (err) => reject(err));
@@ -1112,13 +1465,35 @@ export const openapiRouter = createOpenapiRouter(buildOpenApiYaml);
 }
 
 function routesProductTemplateTs(ctx: ShapeContext): string {
-  return `import { type BuildOpts, buildProductTemplateMaterials, splitAdvancedDefaults } from "${ctx.scope}/shared/product-template";
+  const hasComponents = ctx.features.has("components");
+  const hasDashboard = ctx.features.has("dashboard");
+  // Each entry carries its own newline: the interpolation sits directly against
+  // the blank line before the next block, so an empty list must add nothing.
+  const loaderImports = [
+    ...(hasComponents ? ['import { loadCompiledComponents } from "../lib/components.ts";'] : []),
+    ...(hasDashboard ? ['import { loadDashboardFiles } from "../lib/dashboards.ts";'] : []),
+  ]
+    .map((line) => `${line}\n`)
+    .join("");
+  const buildOpts = [
+    "library",
+    "advanced",
+    ...(hasComponents ? ["components: loadCompiledComponents()"] : []),
+    ...(hasDashboard ? ["dashboards: loadDashboardFiles()"] : []),
+  ]
+    .map((entry) => `        ${entry},`)
+    .join("\n");
+  return `import {
+  type BuildOpts,
+  buildProductTemplateMaterials,
+  splitAdvancedDefaults,
+} from "${ctx.scope}/shared/product-template";
 import { ProductConfigSchema } from "${ctx.scope}/shared/schemas";
 import { packProductTemplate } from "@norskvideo/ctl-product-template-schema/pack";
 import type { ComponentLibrary } from "@norskvideo/norsk-studio-builder";
 import { Router } from "express";
 import defaultExample from "../../../examples/default/input.json" with { type: "json" };
-
+${loaderImports}
 // Starter configs, mirrored in manifest.ts's defaultProductTemplates[]. JSON
 // imported at module load so the bundler inlines it — the deployed container
 // doesn't ship the examples/ source tree. Keep the two in lockstep.
@@ -1141,7 +1516,9 @@ export function makeProductTemplateRouter(library: ComponentLibrary): Router {
       return;
     }
     try {
-      const materials = buildProductTemplateMaterials(parsed.data, { library, advanced });
+      const materials = buildProductTemplateMaterials(parsed.data, {
+${buildOpts}
+      });
       const tar = packProductTemplate(materials);
       res
         .status(200)
@@ -1469,21 +1846,49 @@ function exampleInputJson(_ctx: ShapeContext): string {
 // path-existence lint would look for them in the repo.
 
 function readmeMd(ctx: ShapeContext): string {
+  const optional = [
+    ...(ctx.features.has("components")
+      ? ["- `components/` — this product's own Studio nodes, packed into the product-template tar."]
+      : []),
+    ...(ctx.features.has("dashboard")
+      ? ["- `dashboard/` — the per-instance operator SPA; builds into `dashboards/`, which Studio serves."]
+      : []),
+    ...(ctx.features.has("frontend")
+      ? ["- `frontend/` — the configure screen the backend serves at /configure and norsk-ctl iframes."]
+      : []),
+  ]
+    .map((line) => `${line}\n`)
+    .join("");
+  const screen = ctx.features.has("views")
+    ? " The operator screen is the component's own fullscreen view, inside Studio."
+    : ctx.features.has("dashboard")
+      ? " The operator screen is a dashboard Studio serves per instance."
+      : "";
   return `# ${ctx.name}
 
-A Norsk product for norsk-ctl: a backend-only turnkey. The control plane is a
-small service the daemon runs (the manifest, the product-template build, the
-documentation); the media path is a Norsk Studio workflow the product composes.
+A Norsk product for norsk-ctl. The control plane is a small service the daemon
+runs (the manifest, the product-template build, the documentation); the media
+path is a Norsk Studio workflow the product composes.${screen}
 
 ## Layout
 
 - \`shared/\` — the product's config schema, workflow composer and manifest.
-- \`backend/\` — the control-plane service (manifest, product-template build, docs).
+${optional}- \`backend/\` — the control-plane service (manifest, product-template build, docs).
 - \`examples/\` — starter configs; \`examples/default/input.json\` is the default template.
 - \`tests/\` — unit, image and demo tiers; \`tests/demo.spec.ts\` is the customer journey.
 - \`docs/\` — reader-facing documents; \`docs/README.md\` is the index.
 - \`deployment/\` — the image build wrapper and the iterate loop.
 
+## First run
+
+1. \`nix develop\` — the dev shell: pinned bun, biome and norsk-ctl.
+2. \`git init && bun install\`
+3. \`UPDATE_SNAPSHOTS=1 bun run test:unit\` — bake the byte-snapshot fixtures, then commit them.
+4. \`bun run check:drift && bun run docs:check && bun run test:unit && bun run typecheck && bun run lint\`
+5. Replace the starter graph in \`shared/src/workflow/\` with the real one,
+   keeping \`INVARIANTS.md\` and its rules tests in step.
+6. \`bun run docs:handover\` — once a daemon has this product added.
+
 ## Dev loop
 
 Everything runs inside the dev shell (\`nix develop .#dev\`), which carries bun,
@@ -1598,12 +2003,26 @@ cd "$(dirname "$0")/../.."
 bun run docs:manual
 `;
 
-export const backendTurnkey: ShapeModule = {
+// The drift-gated core block covers node_modules/, dist/, generated, logs/ and
+// friends; everything a FEATURE's workspace builds has to be named here.
+function gitignoreTail(ctx: ShapeContext): string {
+  const blocks = ["# Repo-specific entries go below (the block above is drift-gated verbatim).\n"];
+  if (ctx.features.has("components")) blocks.push(COMPONENTS_GITIGNORE);
+  if (ctx.features.has("dashboard")) blocks.push(DASHBOARD_GITIGNORE);
+  return blocks.join("\n");
+}
+
+export const turnkey: ShapeModule = {
   claudeHead,
   claudeTail,
+  gitignoreTail,
   rootTsconfigInclude: ["tests/**/*"],
   files(ctx: ShapeContext): GeneratedFile[] {
     return [
+      ...(ctx.features.has("components") ? componentsFiles(ctx) : []),
+      ...(ctx.features.has("views") ? viewsFiles(ctx) : []),
+      ...(ctx.features.has("dashboard") ? dashboardFiles(ctx) : []),
+      ...(ctx.features.has("frontend") ? frontendFiles(ctx) : []),
       { path: "package.json", content: rootPackageJson(ctx) },
       { path: "INVARIANTS.md", content: invariantsMd(ctx) },
       { path: ".dockerignore", content: DOCKERIGNORE },
@@ -1625,18 +2044,18 @@ export const backendTurnkey: ShapeModule = {
       { path: "shared/src/index.ts", content: SHARED_INDEX_TS },
       { path: "shared/src/version.ts", content: versionTs(ctx) },
       { path: "shared/src/version.test.ts", content: versionTestTs(ctx) },
-      { path: "shared/src/manifest.ts", content: MANIFEST_TS },
-      { path: "shared/src/manifest.test.ts", content: MANIFEST_TEST_TS },
+      { path: "shared/src/manifest.ts", content: manifestTs(ctx) },
+      { path: "shared/src/manifest.test.ts", content: manifestTestTs(ctx) },
       { path: "shared/src/schemas/index.ts", content: SCHEMAS_INDEX_TS },
       { path: "shared/src/schemas/config.ts", content: CONFIG_TS },
       { path: "shared/src/schemas/config.test.ts", content: CONFIG_TEST_TS },
       { path: "shared/src/product-template.ts", content: productTemplateTs(ctx) },
       { path: "shared/src/product-template.test.ts", content: PRODUCT_TEMPLATE_TEST_TS },
-      { path: "shared/src/workflow/index.ts", content: WORKFLOW_INDEX_TS },
-      { path: "shared/src/workflow/ids.ts", content: IDS_TS },
+      { path: "shared/src/workflow/index.ts", content: workflowIndexTs(ctx) },
+      { path: "shared/src/workflow/ids.ts", content: idsTs(ctx) },
       { path: "shared/src/workflow/components.ts", content: COMPONENTS_TS },
-      { path: "shared/src/workflow/studio-library.ts", content: STUDIO_LIBRARY_TS },
-      { path: "shared/src/workflow/compose-workflow.ts", content: COMPOSE_WORKFLOW_TS },
+      { path: "shared/src/workflow/studio-library.ts", content: studioLibraryTs(ctx) },
+      { path: "shared/src/workflow/compose-workflow.ts", content: composeWorkflowTs(ctx) },
       { path: "shared/src/workflow/compose-workflow.test.ts", content: COMPOSE_WORKFLOW_TEST_TS },
       { path: "backend/package.json", content: backendPackageJson(ctx) },
       { path: "backend/tsconfig.json", content: WORKSPACE_TSCONFIG },