@cosmicdrift/kumiko-guards 0.373.0 → 0.377.0

package/README.md

@@ -68,15 +68,16 @@ A POSIX-sh pre-push hook, wired by copying the package's `hooks/pre-push`
 shim to `.husky/pre-push`. The shim execs the nearest executable
 `node_modules/.bin/kumiko-pre-push` from the repo root upwards (so worktrees
 without their own `node_modules` resolve via the parent install) and fails
-closed with a `bun install` / `PRE_PUSH_SKIP=1` hint when none exists. Inside
+closed with a `bun install` hint when none exists. Inside
 the cosmicdriftgamestudio parent workspace it runs a scoped `bun check` for
 the pushing repo only; in a standalone clone it runs the repo's own
 `package.json` `test` script. From a `.wt/<name>` worktree under the parent
 workspace it runs a tracked `scripts/check-wt.sh` if present, otherwise the
 worktree's own `package.json` scripts `typecheck`, `lint`, `test`, and
 `test:dom` (whichever are declared), directly in the worktree — the parent's
-`bun check` would otherwise check the main checkout instead. Set
-`PRE_PUSH_SKIP=1` to bypass.
+`bun check` would otherwise check the main checkout instead. There is no
+bypass switch. A `check-wt.sh` that wraps this hook sets `KUMIKO_CHECK_WT=1`
+so the hook does not call it again.
 
 Extension point: a tracked, executable `scripts/pre-push-extra.sh` runs
 before the main check in every branch (worktree, parent-scoped, and

package/hooks/pre-push

@@ -1,10 +1,4 @@
 #!/usr/bin/env sh
-# PRE_PUSH_SKIP is checked here too so the bypass works even without node_modules.
-if [ "${PRE_PUSH_SKIP:-0}" = "1" ]; then
-  echo "[pre-push] PRE_PUSH_SKIP=1 — hook skipped"
-  exit 0
-fi
-
 REPO_ROOT="$(git rev-parse --show-toplevel)"
 if [ -z "$REPO_ROOT" ]; then
   echo "[pre-push] FATAL: git rev-parse --show-toplevel failed — refusing push" >&2
@@ -33,7 +27,7 @@ done
 
 if [ -z "$BIN" ]; then
   echo "[pre-push] kumiko-pre-push not found in any node_modules/.bin above $REPO_ROOT." >&2
-  echo "Run \`bun install\`, or set PRE_PUSH_SKIP=1 to bypass this hook." >&2
+  echo "Run \`bun install\`." >&2
   exit 1
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.373.0",
+  "version": "0.377.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -21,6 +21,14 @@
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./repo-manifest": {
+      "types": "./src/repo-manifest/index.ts",
+      "default": "./src/repo-manifest/index.ts"
+    },
+    "./repo-manifest/app-ports": {
+      "types": "./src/repo-manifest/app-ports/index.ts",
+      "default": "./src/repo-manifest/app-ports/index.ts"
     }
   },
   "bin": {
@@ -28,8 +36,8 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.373.0",
-    "ts-morph": "^28.0.0"
+    "ts-morph": "^28.0.0",
+    "zod": "^4.4.3"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -41,5 +49,16 @@
     "hooks",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "peerDependencies": {
+    "@cosmicdrift/kumiko-framework": ">=0.366.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@cosmicdrift/kumiko-framework": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-framework": "0.377.0"
+  }
 }

package/src/_lib/agent-docs.ts

@@ -14,7 +14,7 @@ import { type ExportedDeclarations, type JSDocableNode, Node, Project, ts } from
 export const AGENT_DOCS_DIR = "packages/framework/agents";
 
 const FEATURE_MANIFEST_REL = "samples/apps/use-all-bundled/feature-manifest.json";
-const RENDERER_WEB_INDEX_REL = "packages/renderer-web/src/index.ts";
+const RENDERER_WEB_INDEX_REL = "packages/renderer/src/web/index.ts";
 const RECIPES_REL = "samples/recipes";
 const RECIPE_SLUG_RE = /^[a-z0-9-]+$/;
 const SOURCE_EXTENSIONS = [".ts", ".tsx"];
@@ -286,7 +286,7 @@ function renderWidgets(repoRoot: string): string {
     const rows = entries.map(([name, description]) => [`\`${name}\``, description]);
     sections.push(`## ${group}\n\n${table(["Name", "Description"], rows)}`);
   }
-  const intro = "Value exports of `@cosmicdrift/kumiko-renderer-web`.";
+  const intro = "Value exports of `@cosmicdrift/kumiko-renderer/web`.";
   return finishFile(RENDERER_WEB_INDEX_REL, `# Widgets\n\n${intro}\n\n${sections.join("\n\n")}`);
 }
 

package/src/_lib/primitives-access.ts

@@ -1,16 +1,20 @@
 import type { SourceFile } from "ts-morph";
 
-const RENDERER_WEB_MODULE = "@cosmicdrift/kumiko-renderer-web";
+const RENDERER_WEB_MODULES: ReadonlySet<string> = new Set([
+  "@cosmicdrift/kumiko-renderer/web",
+  "@cosmicdrift/kumiko-renderer-web",
+]);
 
 // Shared by every "raw HTML tag instead of framework primitive" guard
 // (guard-no-custom-primitives, guard-raw-interactive-elements): proves the
 // primitive set was reachable in this file — either an import from
-// @cosmicdrift/kumiko-renderer-web (any symbol), or a `usePrimitives` named
-// import, which lives in @cosmicdrift/kumiko-renderer (headless layer), not
-// only in -web (see kumiko-enterprise/packages/ai-agent/src/web/turn-cards.tsx).
+// @cosmicdrift/kumiko-renderer/web (any symbol; the deprecated
+// @cosmicdrift/kumiko-renderer-web shim counts too), or a `usePrimitives`
+// named import, which lives in the shared layer of @cosmicdrift/kumiko-renderer,
+// not only in /web (see kumiko-enterprise/packages/ai-agent/src/web/turn-cards.tsx).
 export function hasPrimitivesAccess(sf: SourceFile): boolean {
   for (const imp of sf.getImportDeclarations()) {
-    if (imp.getModuleSpecifierValue() === RENDERER_WEB_MODULE) return true;
+    if (RENDERER_WEB_MODULES.has(imp.getModuleSpecifierValue())) return true;
     if (imp.getNamedImports().some((named) => named.getName() === "usePrimitives")) {
       return true;
     }

package/src/_lib/roots.ts

@@ -17,12 +17,12 @@ import {
   type RepoManifest,
   RepoManifestError,
   type RepoManifestSource,
-} from "@cosmicdrift/kumiko-repo-manifest";
+} from "../repo-manifest/index.ts";
 import { gitEnv } from "./git-env";
 
-export type { RepoKind } from "@cosmicdrift/kumiko-repo-manifest";
+export type { RepoKind } from "../repo-manifest/index.ts";
 
-import type { RepoKind } from "@cosmicdrift/kumiko-repo-manifest";
+import type { RepoKind } from "../repo-manifest/index.ts";
 
 // Worktrees (`.wt/kumiko-framework-*`) keep this package name, so it is stable across checkouts.
 const FRAMEWORK_PACKAGE_NAME = "kumiko-framework";

package/src/_lib/scan-scope.ts

@@ -1,7 +1,7 @@
 import { realpathSync } from "node:fs";
 import { join, sep } from "node:path";
-import { type RepoKind, repoKindSchema } from "@cosmicdrift/kumiko-repo-manifest";
 import { Glob } from "bun";
+import { type RepoKind, repoKindSchema } from "../repo-manifest/index.ts";
 import type { RepoRoot } from "./roots";
 
 // Security-shaped guards name this explicitly: the default skips "tooling" roots, and a one-word manifest kind must not switch them off.

package/src/changes.json

@@ -1,4 +1,42 @@
 [
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "guard-unsafe-append-event",
+    "detail": "Flags ctx.unsafeAppendEvent outside migrations/, upcasters/ and tests. Existing call sites are frozen per file in .kumiko-unsafe-append-event-baseline.json and the count may only shrink; repos without the file get a warning only."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "repo-manifest moved into guards",
+    "detail": "The kumiko.json schema and loader are exported from @cosmicdrift/kumiko-guards/repo-manifest, the app port reader from @cosmicdrift/kumiko-guards/repo-manifest/app-ports. @cosmicdrift/kumiko-repo-manifest now only re-exports them and is removed after the consumer pass of wave 4. @cosmicdrift/kumiko-framework is an optional peer for the app-ports subpath.",
+    "migration": "Run bun kumiko-upgrade --apply, or bun kumiko codemod package-merge . --write. It rewrites imports of @cosmicdrift/kumiko-repo-manifest (and its /app-ports subpath) to @cosmicdrift/kumiko-guards/repo-manifest and replaces the dependency in package.json with kumiko-guards.",
+    "codemod": "scripts/codemod/package-merge.ts"
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "renderer-boundaries guard scans headless and live for imports only",
+    "detail": "The headless and live subtrees of kumiko-renderer must not import react-dom, jsdom or renderer-web; the symbol and JSX rules of the shared layer no longer apply to them. The section-fields-raw scope follows the moved headless sources."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "renderer-boundaries guard leaves the web subtree unscanned",
+    "detail": "renderer/src/web may use the DOM and every web dependency; the shared renderer root and headless/live must not import it. The tailwind-scan-surface guard follows the new stylesheet location through package exports and shim imports."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "comment-lang touched mode pairs renames",
+    "detail": "The touched mode diffs a moved file against its old path, so moving a file no longer counts every German comment in it as new."
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "The pre-push bypass is gone",
+    "detail": "PRE_PUSH_SKIP no longer skips the hook, neither in the shipped hook nor in kumiko-pre-push. KUMIKO_CHECK_WT=1 only stops the hook from re-entering a wrapping scripts/check-wt.sh. The i18n-keys guard treats keys defined by installed @cosmicdrift packages as known."
+  },
   {
     "version": "0.371.0",
     "type": "improvement",

package/src/guard-agent-docs-drift.ts

@@ -2,7 +2,7 @@
 /**
  * Guard: the generated agent docs under `packages/framework/agents/` must
  * match what `bun run gen:agent-docs` renders from the current sources
- * (feature manifest, renderer-web exports, sample recipes), and every
+ * (feature manifest, renderer web exports, sample recipes), and every
  * `agents/<file>.md` path the hand-written `packages/framework/AGENTS.md`
  * points at must exist in that generated set.
  *

package/src/guard-comment-lang.ts

@@ -266,6 +266,23 @@ function gitOrFail(args: readonly string[], cwd: string, message: string): strin
 
 const REWRITE_HINT = `Translate new German comments to English (why, not what), or if deliberate:\n    // ${IGNORE_TAG} <reason>`;
 
+// A path-limited diff cannot pair a rename, so every comment of a moved file would read as added.
+function readRenamedFrom(gitToplevel: string, mergeBase: string): Map<string, readonly string[]> {
+  const renamedFrom = new Map<string, readonly string[]>();
+  const fields = gitOrFail(
+    ["diff", "--name-status", "-z", "-M", "--diff-filter=R", mergeBase, "HEAD"],
+    gitToplevel,
+    "Touched mode: git diff --name-status failed. Check the git error below.",
+  )
+    .split("\0")
+    .filter(Boolean);
+  for (let i = 0; i + 2 < fields.length; i += 3) {
+    const [, oldPath, newPath] = fields.slice(i, i + 3);
+    if (oldPath !== undefined && newPath !== undefined) renamedFrom.set(newPath, [oldPath]);
+  }
+  return renamedFrom;
+}
+
 function runTouchedMode(
   argv: readonly string[],
   root: string,
@@ -304,6 +321,8 @@ function runTouchedMode(
     .split("\0")
     .filter(Boolean);
 
+  const renamedFrom = readRenamedFrom(gitToplevel, mergeBase);
+
   // The commits being pushed are checked, not the working tree: contents come from
   // HEAD so line numbers match the `mergeBase..HEAD` diff. Scan scope is keyed
   // relative to root, git output relative to the toplevel.
@@ -321,7 +340,17 @@ function runTouchedMode(
     if (candidates.length === 0) continue;
     const addedLines = parseAddedLineRanges(
       gitOrFail(
-        ["--literal-pathspecs", "diff", "--unified=0", mergeBase, "HEAD", "--", file],
+        [
+          "--literal-pathspecs",
+          "diff",
+          "-M",
+          "--unified=0",
+          mergeBase,
+          "HEAD",
+          "--",
+          file,
+          ...(renamedFrom.get(file) ?? []),
+        ],
         gitToplevel,
         `Touched mode: git diff --unified=0 failed for ${file}. Check the git error below.`,
       ),

package/src/guard-direct-fetch.ts

@@ -46,8 +46,8 @@ const EXCLUDE =
 // Prefixed by RepoRoot.name (not kind): kind "app" is shared across
 // unregistered repos (infra#560).
 
-// packages/http/src/egress.ts IS the egress() implementation.
-const ALLOWLIST = [/^kumiko-framework\/packages\/http\/src\/egress\.ts$/];
+// packages/framework/src/http/egress.ts IS the egress() implementation.
+const ALLOWLIST = [/^kumiko-framework\/packages\/framework\/src\/http\/egress\.ts$/];
 const ALLOW_MARKER = "guard-allow: same-origin fetch";
 
 interface Violation {

package/src/guard-html-escape.ts

@@ -3,7 +3,7 @@
  * Guard: HTML-building template literals must escape every interpolation.
  *
  * XSS protection in this codebase is a callsite convention
- * (escapeHtml/escapeHtmlAttr from kumiko-headless) — this guard makes the
+ * (escapeHtml/escapeHtmlAttr from kumiko-renderer/headless) — this guard makes the
  * convention enforceable. A template literal counts as HTML-building when
  * its static text contains a known HTML/MJML/SVG tag. Every interpolation
  * inside it must then be recognizably safe:
@@ -409,7 +409,7 @@ function scanFile(sf: SourceFile): UnsafeSite[] {
 export const guard: AstGuard = {
   name: "HTML-Escape Guard",
   scan: SCAN,
-  hint: "Escape interpolation in an HTML template literal: escapeHtml()/escapeHtmlAttr() from @cosmicdrift/kumiko-headless. Mark pre-rendered HTML with a `*Html` name; type static copy tables `as const`; deliberate exception with `// html-ok: <why>`.",
+  hint: "Escape interpolation in an HTML template literal: escapeHtml()/escapeHtmlAttr() from @cosmicdrift/kumiko-renderer/headless. Mark pre-rendered HTML with a `*Html` name; type static copy tables `as const`; deliberate exception with `// html-ok: <why>`.",
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
     for (const sf of files) {

package/src/guard-i18n-keys.ts

@@ -11,7 +11,13 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import * as path from "node:path";
-import { type Node, type ObjectLiteralExpression, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type Node,
+  type ObjectLiteralExpression,
+  Project,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
 import { type AstGuard, type GuardOutcome, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
 const ROOT = process.cwd();
@@ -50,11 +56,11 @@ function isI18nBundleFile(filePath: string): boolean {
   return (
     /\/i18n\//.test(filePath) ||
     // Flat single-file bundle (src/i18n.ts), same status as src/i18n/index.ts.
-    /\/i18n\.ts$/.test(filePath) ||
+    /\/i18n\.(ts|js)$/.test(filePath) ||
     /\/features\/[^/]+\/i18n\./.test(filePath) ||
     // Covers any depth below bundled-features/src/<feature>/
     // (e.g. also .../schema/i18n.ts), not just exactly one level.
-    /bundled-features\/src\/.*\/i18n\.ts$/.test(filePath)
+    /bundled-features\/(src|dist)\/.*\/i18n\.(ts|js)$/.test(filePath)
   );
 }
 
@@ -370,7 +376,54 @@ export function resolveExpectedLocales(root: string = ROOT): Set<string> {
   return new Set(["de", "en"]);
 }
 
+// Published packages ship `dist` (compiled JS) only; workspace links also carry `src`.
+const INSTALLED_FRAMEWORK_SOURCES = [
+  "kumiko-*/{src,dist}/**/*.{ts,tsx,js}",
+  "!kumiko-*/**/__tests__/**",
+  "!kumiko-*/**/*.test.{ts,tsx,js}",
+  "!kumiko-*/**/*.d.ts",
+];
+
+/** Every `node_modules/@cosmicdrift` from the app root upwards: Node resolves per package, so an app's own
+ *  scope dir (a few linked packages) must not hide the hoisted one of the bun workspace above it. */
+function findInstalledScopeDirs(root: string): string[] {
+  const dirs: string[] = [];
+  let curr = path.resolve(root);
+  for (;;) {
+    const candidate = path.join(curr, "node_modules/@cosmicdrift");
+    if (existsSync(candidate)) dirs.push(candidate);
+    const parent = path.dirname(curr);
+    if (parent === curr) return dirs;
+    curr = parent;
+  }
+}
+
+/** Keys the installed framework packages define, so an app may use them without redefining. */
+export function collectInstalledFrameworkKeys(root: string = ROOT): Set<string> {
+  if (isFrameworkMonorepo(root)) return new Set();
+  // allowJs: definition lookup through imports must follow into the compiled .js files.
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: { allowJs: true },
+  });
+  for (const scopeDir of findInstalledScopeDirs(root)) {
+    project.addSourceFilesAtPaths(
+      INSTALLED_FRAMEWORK_SOURCES.map((glob) =>
+        glob.startsWith("!") ? `!${path.join(scopeDir, glob.slice(1))}` : path.join(scopeDir, glob),
+      ),
+    );
+  }
+  const keys = new Set<string>();
+  for (const sf of project.getSourceFiles()) {
+    for (const entry of collectInlineTranslationsDefinedKeys(sf)) keys.add(entry.fullKey);
+    for (const entry of collectBundleDefinedKeys(sf)) keys.add(entry.fullKey);
+  }
+  return keys;
+}
+
 export type I18nKeysRunOptions = {
+  /** Inject the framework keys of the installed packages — tests must not scan node_modules. */
+  readonly installedFrameworkKeys?: () => ReadonlySet<string>;
   /** Inject expected locales per owning root — tests must not rely on process.cwd(). */
   readonly expectedLocalesForRoot?: (root: string) => Set<string>;
 };
@@ -391,7 +444,13 @@ export function checkI18nKeys(
   }
 
   const definedSet = new Set(definedKeys.map((d) => d.fullKey));
-  const missing = usedKeys.filter((u) => !definedSet.has(u.key));
+  const undefinedInApp = usedKeys.filter((u) => !definedSet.has(u.key));
+  // Scanning node_modules is slow; only pay for it when a key is unresolved.
+  const installedKeys =
+    undefinedInApp.length === 0
+      ? new Set<string>()
+      : (options.installedFrameworkKeys ?? collectInstalledFrameworkKeys)();
+  const missing = undefinedInApp.filter((u) => !installedKeys.has(u.key));
   const resolveLocales = options.expectedLocalesForRoot ?? resolveExpectedLocales;
   const expectedByRoot = new Map<string, Set<string>>();
   const expectedForFile = (rel: string): Set<string> => {

package/src/guard-no-custom-primitives.ts

@@ -89,7 +89,7 @@ const rawFormHtmlBaseline = baselineRatchet({
   unit: "raw form HTML finding(s)",
 });
 const RAW_FORM_HTML_REMEDIATION =
-  "Use a framework widget (@cosmicdrift/kumiko-renderer-web: Field/Input, ComboboxInput, …) " +
+  "Use a framework widget (@cosmicdrift/kumiko-renderer/web: Field/Input, ComboboxInput, …) " +
   `or usePrimitives(). Real exception: // ${IGNORE_TAG} <reason>`;
 
 // The rule is new: measured backlog is 0 in every locally checked repo
@@ -166,7 +166,7 @@ export const guard: AstGuard = {
   name: "No-Custom-Primitives Guard (App-Repos)",
   scan: SCAN,
   hint:
-    "Use a framework widget (@cosmicdrift/kumiko-renderer-web: StatCard, SectionCard, StatusBadge, QueryTable, Charts, …) " +
+    "Use a framework widget (@cosmicdrift/kumiko-renderer/web: StatCard, SectionCard, StatusBadge, QueryTable, Charts, …) " +
     `or usePrimitives(). Real domain component without a framework equivalent: // ${IGNORE_TAG} <reason>`,
   run: (files: readonly SourceFile[]) => analyse(files, true),
 };

package/src/guard-no-direct-fs.ts

@@ -83,7 +83,6 @@ const ALLOWLIST: readonly AllowEntry[] = [
 
   // Guard runner + repo-manifest loader: read the scanned repo tree at dev/CI time, no request input as path.
   { repo: "kumiko-framework", pattern: /^packages\/guards\/src\// },
-  { repo: "kumiko-framework", pattern: /^packages\/repo-manifest\/src\// },
 
   // CLI (@cosmicdrift/kumiko-cli): local dev/CI tooling reading the repo tree, no request input as path.
   { repo: "kumiko-framework", pattern: /^packages\/cli\/src\// },

package/src/guard-primitives-discipline.ts

@@ -3,13 +3,10 @@
  * Guard: enforces that app-/feature-web code uses UI building blocks from
  * the framework primitives, not hand-rolled Tailwind on raw HTML tags.
  *
- * Why: hand-rolled Tailwind in `web/` folders costs twice:
- *   1. Style drift — every renderer/theme update then has to be re-applied
- *      to each hand-tailwound screen individually.
- *   2. Multi-platform lock-out — native (renderer-native) has no
- *      `<table>`, `<form>`, `<button>`. Direct DOM tags bind the code to
- *      web. Framework primitives (`<DataTable>`, `<Form>`, `<Button>`) are
- *      contractually platform-neutral.
+ * Why: hand-rolled Tailwind in `web/` folders costs twice: every
+ * renderer/theme update then has to be re-applied to each hand-tailwound
+ * screen individually (style drift), and direct DOM tags bypass the
+ * primitives contract (`<DataTable>`, `<Form>`, `<Button>`).
  *
  * Forbidden in app-/feature-web code:
  *
@@ -20,7 +17,7 @@
  *   <select>                                →  <ComboboxInput>
  *   <textarea>                              →  <Input kind="textarea">
  *   <dialog>                                →  <DefaultDialog>
- *   alert() / window.alert()               →  <DefaultDialog> from @cosmicdrift/kumiko-renderer-web
+ *   alert() / window.alert()               →  <DefaultDialog> from @cosmicdrift/kumiko-renderer/web
  *   className "bg-card" (hand-rolled card) →  <Card> (slots/options)
  *   className "mx-auto" + "max-w-*" (hand-rolled screen container)
  *                                           →  <PageSection maxWidth> (3xl/4xl/full)
@@ -63,7 +60,7 @@ const FORBIDDEN_TAGS: ReadonlyArray<{
 const FORBIDDEN_CALLS: ReadonlyArray<{
   readonly call: string;
   readonly counterpart: string;
-}> = [{ call: "alert", counterpart: "<DefaultDialog> from @cosmicdrift/kumiko-renderer-web" }];
+}> = [{ call: "alert", counterpart: "<DefaultDialog> from @cosmicdrift/kumiko-renderer/web" }];
 
 // Forbidden className tokens: an allowed tag (`<div>`), but the class gives
 // away hand-rolled primitive chrome. `bg-card` is the dedicated card-surface

package/src/guard-raw-classname.ts

@@ -90,7 +90,7 @@ export const guard: AstGuard = {
   name: "Raw-ClassName Guard (App-Repos)",
   scan: SCAN,
   hint:
-    "Design-bearing classes belong in widgets/theme tokens (@cosmicdrift/kumiko-renderer-web widgets/, --color-status-*). " +
+    "Design-bearing classes belong in widgets/theme tokens (@cosmicdrift/kumiko-renderer/web widgets/, --color-status-*). " +
     `Justified exception: // ${IGNORE_TAG} <reason>`,
   run(files: readonly SourceFile[]) {
     const violations: GuardViolation[] = [];

package/src/guard-raw-interactive-elements.ts

@@ -2,7 +2,7 @@
 /**
  * Guard: raw interactive HTML elements in feature UI. <a>, <details> and
  * <summary> each have a framework replacement (usePrimitives().Link,
- * CollapsibleSection from @cosmicdrift/kumiko-renderer-web) but nothing was
+ * CollapsibleSection from @cosmicdrift/kumiko-renderer/web) but nothing was
  * checking for them — turn-cards.tsx/agent-layer.tsx (raw <details>/<summary>)
  * and agent-settings.tsx (raw <a href>) shipped past CI in kumiko-enterprise.
  *
@@ -56,8 +56,8 @@ type BannedTag = "a" | "details" | "summary";
 
 const REPLACEMENT: Readonly<Record<BannedTag, string>> = {
   a: "usePrimitives().Link",
-  details: "CollapsibleSection (@cosmicdrift/kumiko-renderer-web)",
-  summary: "CollapsibleSection (@cosmicdrift/kumiko-renderer-web)",
+  details: "CollapsibleSection (@cosmicdrift/kumiko-renderer/web)",
+  summary: "CollapsibleSection (@cosmicdrift/kumiko-renderer/web)",
 };
 
 function isBannedTag(tag: string): tag is BannedTag {
@@ -110,7 +110,7 @@ const createBaseline = (baselineRoot: string) =>
 
 const REMEDIATION =
   "Framework replacement: <a> → usePrimitives().Link, <details>/<summary> → CollapsibleSection " +
-  `(@cosmicdrift/kumiko-renderer-web). Genuine exception: // ${IGNORE_TAG} <reason>`;
+  `(@cosmicdrift/kumiko-renderer/web). Genuine exception: // ${IGNORE_TAG} <reason>`;
 
 function analyse(
   files: readonly SourceFile[],

package/src/guard-renderer-boundaries.ts

@@ -3,14 +3,22 @@
  * Guard: prevents `@cosmicdrift/kumiko-renderer` (shared, platform-neutral)
  * from touching DOM- or platform-specific APIs. As soon as window/document/
  * EventSource/react-dom show up, the separation is broken and the code
- * belongs in `@cosmicdrift/kumiko-renderer-web` (or renderer-native) instead.
+ * belongs in `src/web` instead.
+ *
+ * `src/web/**` is the browser layer and not scanned at all: it may import
+ * everything. `src/headless/**` and `src/live/**` only get the import rules:
+ * the apex page builder emits HTML strings and the live dispatcher is a fetch
+ * client, so the symbol and JSX-tag rules would be noise there. They stay free
+ * of react-dom, jsdom and any import of `src/web`.
  *
  * Deliberately simple: a regex scan over the source text. False positives
  * (e.g. "window" in a string literal) are possible but rare — the guard is a
  * maintenance alarm, not a semantic proof.
  *
  * Checked:
- *   - Imports:  react-dom/*, jsdom, @cosmicdrift/kumiko-renderer-web, @cosmicdrift/kumiko-renderer-native
+ *   - Imports:  react-dom/*, jsdom, `src/web` (relative or as
+ *               @cosmicdrift/kumiko-renderer/web), and the deprecated renderer-web /
+ *               headless / dispatcher-live shims (they depend on this package)
  *   - Symbols:  window., document., location., history., localStorage,
  *               sessionStorage, navigator., EventSource, fetch(
  *               (bare — unqualified), HTMLElement, createRoot
@@ -26,8 +34,10 @@ import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
 const FORBIDDEN_IMPORTS = [
   /from ["']react-dom(?:\/.*)?["']/,
   /from ["']jsdom["']/,
-  /from ["']@cosmicdrift\/kumiko-renderer-web["']/,
-  /from ["']@cosmicdrift\/kumiko-renderer-native["']/,
+  /from ["']@cosmicdrift\/kumiko-renderer-web(?:\/.*)?["']/,
+  /from ["']@cosmicdrift\/kumiko-renderer\/web(?:\/.*)?["']/,
+  /from ["'](?:\.\.?\/)+web(?:\/.*)?["']/,
+  /from ["']@cosmicdrift\/kumiko-headless(?:\/.*)?["']/,
   /from ["']@cosmicdrift\/kumiko-dispatcher-live["']/,
 ];
 
@@ -59,6 +69,12 @@ const FORBIDDEN_SYMBOLS = [
 // after whitespace/newline/>, not after an identifier character).
 const FORBIDDEN_JSX_TAG = /(^|\s|>|\()<([a-z][a-zA-Z0-9-]*)(?=[\s/>])/g;
 
+// Subtrees of packages/renderer/src that carry only the import rules.
+const IMPORT_RULES_ONLY_DIRS = ["headless", "live"] as const;
+
+// The browser layer may import anything, so it is not scanned.
+const UNSCANNED_TOP_LEVEL_DIRS = ["web"] as const;
+
 type Violation = {
   readonly file: string;
   readonly line: number;
@@ -66,13 +82,14 @@ type Violation = {
   readonly excerpt: string;
 };
 
-function walk(dir: string): string[] {
+function walk(dir: string, skippedDirs: readonly string[] = []): string[] {
   const out: string[] = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === "__tests__") continue;
       if (entry.name === "node_modules" || entry.name === "dist") continue;
+      if (skippedDirs.includes(entry.name)) continue;
       out.push(...walk(full));
       continue;
     }
@@ -83,7 +100,7 @@ function walk(dir: string): string[] {
   return out;
 }
 
-export function findViolations(file: string, root: string): Violation[] {
+export function findViolations(file: string, root: string, importRulesOnly = false): Violation[] {
   const text = fs.readFileSync(file, "utf-8");
   const lines = text.split("\n");
   const violations: Violation[] = [];
@@ -104,6 +121,7 @@ export function findViolations(file: string, root: string): Violation[] {
         });
       }
     }
+    if (importRulesOnly) continue;
     for (const pattern of FORBIDDEN_SYMBOLS) {
       if (pattern.test(line)) {
         violations.push({
@@ -126,9 +144,17 @@ export function findViolations(file: string, root: string): Violation[] {
   return violations;
 }
 
+function isImportRulesOnly(file: string): boolean {
+  return IMPORT_RULES_ONLY_DIRS.some((dir) =>
+    file.includes(
+      `${path.sep}packages${path.sep}renderer${path.sep}src${path.sep}${dir}${path.sep}`,
+    ),
+  );
+}
+
 export const check: RepoCheck = {
   name: "Renderer-Boundaries Guard",
-  hint: "@cosmicdrift/kumiko-renderer must not use DOM/browser/platform APIs. Platform-specific code belongs in @cosmicdrift/kumiko-renderer-web (or renderer-native).",
+  hint: "@cosmicdrift/kumiko-renderer must not use DOM/browser/platform APIs. Platform-specific code belongs in packages/renderer/src/web.",
   run(roots) {
     const frameworkRoots = roots.filter((r) => r.kind === "framework");
     const scanDirs = frameworkRoots
@@ -138,10 +164,10 @@ export const check: RepoCheck = {
       return { violations: [], matchedFiles: 0, notApplicable: true };
     }
     const files: string[] = [];
-    for (const dir of scanDirs) files.push(...walk(dir));
+    for (const dir of scanDirs) files.push(...walk(dir, UNSCANNED_TOP_LEVEL_DIRS));
     const root = frameworkRoots[0]?.absPath ?? process.cwd();
     const violations = files.flatMap((file) =>
-      findViolations(file, root).map((v) => ({
+      findViolations(file, root, isImportRulesOnly(file)).map((v) => ({
         file: v.file,
         line: v.line,
         message: `[${v.rule}] ${v.excerpt}`,

package/src/guard-section-fields-raw.ts

@@ -68,7 +68,7 @@ const SCAN: ScanSpec = {
     "packages/framework/src/engine/**",
     "packages/framework/src/i18n/**",
     "packages/testing/src/helpers/**",
-    "packages/headless/src/**",
+    "packages/renderer/src/headless/**",
     "packages/renderer/src/app/**",
   ],
 };