@cosmicdrift/kumiko-guards 0.374.0 → 0.378.0

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-pre-es-patterns.ts

@@ -68,6 +68,8 @@ type Pattern = {
 // identifier in the AST (not in strings, not in comments).
 function identifierHits(sf: SourceFile, name: string): Array<{ line: number; snippet: string }> {
   const out: Array<{ line: number; snippet: string }> = [];
+  // Cheap text prefilter: a full descendant walk over every file costs seconds.
+  if (!sf.getFullText().includes(name)) return out;
   for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
     if (id.getText() !== name) continue;
     out.push({
@@ -85,6 +87,7 @@ function stringLiteralHits(
   literal: string,
 ): Array<{ line: number; snippet: string }> {
   const out: Array<{ line: number; snippet: string }> = [];
+  if (!sf.getFullText().includes(literal)) return out;
   for (const lit of sf.getDescendantsOfKind(SyntaxKind.StringLiteral)) {
     if (lit.getLiteralText() !== literal) continue;
     out.push({
@@ -129,6 +132,7 @@ const PATTERNS: readonly Pattern[] = [
       // Match `.postEvent(` property accesses to distinguish from the word
       // "postEvent" in prose. Identifier scan would miss method invocations.
       const out: Array<{ line: number; snippet: string }> = [];
+      if (!sf.getFullText().includes("postEvent")) return out;
       for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
         if (pa.getName() !== "postEvent") continue;
         // Only flag when invoked as a method — a property read named

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/**`, `src/flow-diagram/**` and `src/live/**` only get
+ * the import rules: the apex page builder emits HTML strings, the flow diagram
+ * emits SVG 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", "flow-diagram", "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/**",
   ],
 };

package/src/guard-tailwind-scan-surface.ts

@@ -2,10 +2,9 @@
 /**
  * Guard: `className` string-literal tokens under kumiko-framework's
  * `packages/bundled-features/src/**` must already be reachable through the
- * real Tailwind `@source` scan surface (`packages/renderer-web/src` +
- * `packages/renderer/src` + `samples/**\/src`, see
- * `packages/renderer-web/src/styles.css`). bundled-features itself is NOT
- * part of that scan surface (infra#654, follow-up to
+ * real Tailwind `@source` scan surface (`packages/renderer/src` +
+ * `samples/**\/src`, see `packages/renderer/src/web/styles.css`).
+ * bundled-features itself is NOT part of that scan surface (infra#654, follow-up to
  * kumiko-framework#2498/#2496): expanding `@source` there was verified to
  * work in the monorepo build but makes the standalone npm-consumer case
  * (no monorepo-relative scan path — #359) falsely green. A class used only
@@ -33,7 +32,7 @@
  *   bun guards/guard-tailwind-scan-surface.ts --write-baseline # (re)write the baseline
  *   bun guards/guard-tailwind-scan-surface.ts --no-baseline    # skip the comparison
  */
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import * as path from "node:path";
 import { Glob } from "bun";
 import { type SourceFile, SyntaxKind } from "ts-morph";
@@ -64,7 +63,6 @@ const SCAN: ScanSpec = {
   kinds: ["framework"],
   frameworkWithin: [
     "packages/bundled-features/src/**/*.tsx",
-    "packages/renderer-web/src/**",
     "packages/renderer/src/**",
     "samples/**/src/**",
   ],
@@ -75,7 +73,7 @@ const IGNORE_TAG = "kumiko-lint-ignore tailwind-scan-surface";
 // The allow-set mirrors what Tailwind's own scanner sees over the real
 // @source surface: every string/template-literal text in the file, not
 // just JSX className attributes — cn(...) calls, variant maps and shared
-// class constants in renderer-web/renderer/samples legitimately emit
+// class constants in renderer/samples legitimately emit
 // classes too. No EXCLUDE filter here on purpose: the @source globs
 // themselves scan __tests__/*.test.tsx just the same, so excluding them
 // from the allow-set would manufacture false positives.
@@ -148,7 +146,7 @@ function scan(
         if (token.length === 0 || allowed.has(token)) continue;
         findings.push({ file, line, token });
         console.warn(
-          `  [tailwind-scan-surface WARN] ${file}:${line}  class "${token}" is outside the Tailwind scan surface (renderer-web/src, renderer/src, samples/**/src)`,
+          `  [tailwind-scan-surface WARN] ${file}:${line}  class "${token}" is outside the Tailwind scan surface (renderer/src, samples/**/src)`,
         );
       }
     }
@@ -173,8 +171,8 @@ const tailwindScanSurfaceBaseline = (baselineRoot: string) =>
 // Second, independent rule: a consuming app repo (studio,
 // publicstatus, …) imports Framework AND Enterprise packages by npm name
 // (@cosmicdrift/* resp. @cosmicdriftgamestudio/*). Every one of them that
-// ships .tsx with `className` under its own scan surface (renderer-web +
-// renderer + samples/**/src) needs its own `@source` entry in the app's
+// ships .tsx with `className` under its own scan surface (renderer/src +
+// samples/**/src) needs its own `@source` entry in the app's
 // styles.css — nothing else scans it. Missed cases so far: kumiko-designer
 // in studio (studio#289), kumiko-ai-agent in publicstatus (publicstatus#442)
 // — both fixed by hand, both silent (no build/lint error) until noticed
@@ -244,11 +242,26 @@ function classNameExampleIn(pkgDir: string): string | undefined {
 }
 
 // Resolves `@import "spec";` specifiers in a CSS file to the imported file's
-// absolute path — a bare/package specifier (`@cosmicdrift/kumiko-renderer-
+// absolute path — a bare/package specifier (`@cosmicdrift/kumiko-renderer/
 // web/styles.css`) resolves through the SAME node_modules hop search as a
 // package dependency (it IS one); a relative specifier (`./x.css`) resolves
 // against the importing file's own directory. Unresolvable imports (e.g.
 // Tailwind's own `"tailwindcss"`) are dropped, not thrown on.
+// A subpath like "@scope/name/web/styles.css" only exists as a file through
+// the package's `exports` map ("./web/styles.css" -> "./src/web/styles.css").
+function resolveThroughPackageExports(appRoot: string, spec: string): string | undefined {
+  const [scope, name, ...rest] = spec.split("/");
+  if (scope === undefined || name === undefined || rest.length === 0) return undefined;
+  const pkgDir = resolvePackageDir(appRoot, `${scope}/${name}`);
+  if (pkgDir === undefined) return undefined;
+  const exportsField = readJsonSafe(path.join(pkgDir, "package.json"))?.["exports"];
+  if (typeof exportsField !== "object" || exportsField === null) return undefined;
+  const target = Object.entries(exportsField).find(([key]) => key === `./${rest.join("/")}`)?.[1];
+  if (typeof target !== "string") return undefined;
+  const abs = path.join(pkgDir, target);
+  return existsSync(abs) ? abs : undefined;
+}
+
 function resolveCssImports(cssAbsPath: string, css: string, appRoot: string): string[] {
   const specifiers = [...css.matchAll(/@import\s+["']([^"']+)["']/g)].map((m) => m[1]);
   const resolved: string[] = [];
@@ -262,7 +275,8 @@ function resolveCssImports(cssAbsPath: string, css: string, appRoot: string): st
     // Package-style specifier including its subpath (e.g. "@scope/name/
     // styles.css") — resolvePackageDir's node_modules hop search works
     // unchanged since it only checks existence, file or directory alike.
-    const candidate = resolvePackageDir(appRoot, spec);
+    const candidate =
+      resolvePackageDir(appRoot, spec) ?? resolveThroughPackageExports(appRoot, spec);
     if (candidate !== undefined) resolved.push(candidate);
   }
   return resolved;
@@ -297,8 +311,22 @@ function realpathOrSelf(p: string): string {
   }
 }
 
+// The deprecated renderer-web stylesheet only `@import`s the renderer's, so the
+// chain has to be followed past the first hop.
+function resolveCssImportsTransitively(cssAbsPath: string, css: string, appRoot: string): string[] {
+  const seen = new Set<string>();
+  const queue = resolveCssImports(cssAbsPath, css, appRoot);
+  for (let imported = queue.shift(); imported !== undefined; imported = queue.shift()) {
+    if (seen.has(imported)) continue;
+    seen.add(imported);
+    if (!existsSync(imported) || statSync(imported).isDirectory()) continue;
+    queue.push(...resolveCssImports(imported, readFileSync(imported, "utf-8"), appRoot));
+  }
+  return [...seen];
+}
+
 // A package is covered if an `@source` entry — in the app's own styles.css
-// OR in a CSS file it `@import`s (e.g. renderer-web's, which ships its own
+// OR in a CSS file it `@import`s (e.g. the renderer's web stylesheet, which ships its own
 // @source lines for the framework's scan surface) — resolves, in THIS
 // install layout, to a directory on the same branch as the package's own
 // directory (either one nested inside the other: the entry could scan the
@@ -314,7 +342,7 @@ function isCoveredByImportChain(
   pkgDir: string,
 ): boolean {
   const realPkgDir = realpathOrSelf(pkgDir);
-  for (const imported of resolveCssImports(stylesAbs, css, appRoot)) {
+  for (const imported of resolveCssImportsTransitively(stylesAbs, css, appRoot)) {
     for (const staticDir of sourceStaticDirsFromCss(imported)) {
       const realStaticDir = realpathOrSelf(staticDir);
       if (
@@ -329,6 +357,12 @@ function isCoveredByImportChain(
   return false;
 }
 
+function isRendererWebStylesheetImport(css: string): boolean {
+  return (
+    css.includes("kumiko-renderer/web/styles.css") || css.includes("kumiko-renderer-web/styles.css")
+  );
+}
+
 export function scanSourceCoverage(roots: readonly RepoRoot[]): SourceCoverageFinding[] {
   const findings: SourceCoverageFinding[] = [];
   for (const root of roots) {
@@ -336,14 +370,14 @@ export function scanSourceCoverage(roots: readonly RepoRoot[]): SourceCoverageFi
     const stylesAbs = path.join(root.absPath, APP_STYLES_REL);
     if (!existsSync(stylesAbs)) continue;
     const css = readFileSync(stylesAbs, "utf-8");
-    // Only apps on the renderer-web @source convention are in scope — an
+    // Only apps on the renderer web @source convention are in scope — an
     // app without that @import never had a scan surface to extend.
-    if (!css.includes("kumiko-renderer-web/styles.css")) continue;
+    if (!isRendererWebStylesheetImport(css)) continue;
     const pkg = readJsonSafe(path.join(root.absPath, "package.json"));
     if (!pkg) continue;
     const file = path.relative(ROOT, stylesAbs);
     for (const name of dependencyNames(pkg)) {
-      if (css.includes(name)) continue; // already @source'd (or @import'd, e.g. renderer-web itself)
+      if (css.includes(name)) continue; // already @source'd (or @import'd, e.g. the renderer's web stylesheet itself)
       const dir = resolvePackageDir(root.absPath, name);
       if (dir === undefined) continue;
       const example = classNameExampleIn(dir);
@@ -531,7 +565,7 @@ function checkBaseline(findings: readonly Finding[], baselineRoot: string): Guar
   const resolveLine = (file: string): number => findings.find((f) => f.file === file)?.line ?? 1;
   return tailwindScanSurfaceBaseline(baselineRoot).check(
     baselineCounts(findings),
-    "Class outside the @source scan surface (renderer-web/src, renderer/src, samples/**/src) — reuse a class already emitted there, or move the styling into renderer-web.",
+    "Class outside the @source scan surface (renderer/src, samples/**/src) — reuse a class already emitted there, or move the styling into renderer/src/web.",
     {
       formatDriftRemediation:
         "Run `bun guards/guard-tailwind-scan-surface.ts --write-baseline` once.",
@@ -569,8 +603,8 @@ export function createGuard(options: { readonly baselineRoot?: string } = {}): A
     name: "Tailwind-Scan-Surface Guard",
     scan: SCAN,
     hint:
-      "Tailwind class in bundled-features outside the @source scan surface (renderer-web/src, renderer/src, samples/**/src) " +
-      `— reuse a class already emitted there, or move the styling into renderer-web. Justified exception: // ${IGNORE_TAG} <reason>. ` +
+      "Tailwind class in bundled-features outside the @source scan surface (renderer/src, samples/**/src) " +
+      `— reuse a class already emitted there, or move the styling into renderer/src/web. Justified exception: // ${IGNORE_TAG} <reason>. ` +
       "Package without @source coverage in an app: add an @source entry for both install layouts. " +
       "@source with a node_modules/<pkg>/<segment> path: check whether <pkg> even publishes that segment (package.json files).",
     run: (files, roots = resolveRepoRoots()) => analyse(files, true, roots, baselineRoot),

package/src/guard-unsafe-append-event.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+/**
+ * Guard: reports `ctx.unsafeAppendEvent` (also `ctx["unsafeAppendEvent"]` and destructuring) outside `migrations/`, `upcasters/` and tests.
+ *
+ * `appendEvent` is the typed default, `tryAppendEvent` the optimistic variant. The untyped
+ * `unsafeAppendEvent` skips payload typing and is meant for migrations and upcasters, where the
+ * event type is not knowable at compile time.
+ *
+ * Existing call sites are frozen per file in `.kumiko-unsafe-append-event-baseline.json`; a count
+ * over the baseline fails, at or under passes. Without the file (consumer repos) the guard only
+ * warns.
+ *
+ * Usage:
+ *   bun packages/guards/src/guard-unsafe-append-event.ts                  # compare to baseline
+ *   bun packages/guards/src/guard-unsafe-append-event.ts --write-baseline # freeze current
+ */
+
+import * as path from "node:path";
+
+import { Node, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  ALL_REPO_KINDS,
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  isLocalFinding,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { resolveRepoRoots } from "./_lib/roots";
+
+const SCAN: ScanSpec = {
+  kinds: ALL_REPO_KINDS,
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**", "samples/**"],
+};
+
+const SYMBOL = "unsafeAppendEvent";
+const ALLOWED_PATH = /(^|\/)(migrations|upcasters|__tests__)\/|\.test\.ts$|\.d\.ts$/;
+
+function unsafeAppendEventLines(sf: SourceFile): number[] {
+  const propertyAccesses = sf
+    .getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)
+    .filter((access) => access.getNameNode().getText() === SYMBOL);
+  const elementAccesses = sf
+    .getDescendantsOfKind(SyntaxKind.ElementAccessExpression)
+    .filter((access) => {
+      const argument = access.getArgumentExpression();
+      return (
+        argument !== undefined &&
+        (Node.isStringLiteral(argument) || Node.isNoSubstitutionTemplateLiteral(argument)) &&
+        argument.getLiteralText() === SYMBOL
+      );
+    });
+  const destructurings = sf
+    .getDescendantsOfKind(SyntaxKind.BindingElement)
+    .filter(
+      (element) => (element.getPropertyNameNode() ?? element.getNameNode()).getText() === SYMBOL,
+    );
+  return [...propertyAccesses, ...elementAccesses, ...destructurings].map((node) =>
+    node.getStartLineNumber(),
+  );
+}
+
+type Finding = { readonly file: string; readonly line: number };
+
+function scan(files: readonly SourceFile[], roots = resolveRepoRoots()): Finding[] {
+  const findings: Finding[] = [];
+  for (const sf of files) {
+    const file = relFromRepoRoot(sf.getFilePath(), roots);
+    if (ALLOWED_PATH.test(file)) continue;
+    for (const line of unsafeAppendEventLines(sf)) findings.push({ file, line });
+  }
+  return findings;
+}
+
+function countsPerFile(findings: readonly Finding[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const f of findings.filter(isLocalFinding)) counts[f.file] = (counts[f.file] ?? 0) + 1;
+  return counts;
+}
+
+const GUARD_NAME = "Unsafe-Append-Event Guard";
+const DEFAULT_BASELINE_FILE = path.join(process.cwd(), ".kumiko-unsafe-append-event-baseline.json");
+
+const REMEDIATION =
+  "unsafeAppendEvent drops payload typing. Use ctx.appendEvent (default) or ctx.tryAppendEvent (conflict as result); the untyped variant belongs in migrations/ and upcasters/.";
+
+const REWRITE_COMMAND = `kumiko-guards guards --write-baseline --guard="${GUARD_NAME}"`;
+
+export function createUnsafeAppendEventGuard(baselineFile: string): AstGuard {
+  const baseline = baselineRatchet({
+    file: baselineFile,
+    formatVersion: 1,
+    unit: "unsafeAppendEvent call(s)",
+  });
+  return {
+    name: GUARD_NAME,
+    scan: SCAN,
+    hint: `${REMEDIATION} After a deliberate change: \`${REWRITE_COMMAND}\`.`,
+    run(files, roots = resolveRepoRoots()) {
+      const findings = scan(files, roots);
+      const violations = baseline.check(countsPerFile(findings), REMEDIATION, {
+        formatDriftRemediation: `Run \`${REWRITE_COMMAND}\` once.`,
+        resolveLine: (file) => findings.find((f) => f.file === file)?.line ?? 1,
+      });
+      return { violations };
+    },
+    writeBaseline: (files, roots) => baseline.write(countsPerFile(scan(files, roots))),
+  };
+}
+
+export const guard = createUnsafeAppendEventGuard(DEFAULT_BASELINE_FILE);
+
+if (import.meta.main) {
+  if (process.argv.slice(2).includes("--write-baseline")) {
+    const project = buildSharedProject([guard]);
+    guard.writeBaseline?.(filesForGuard(project, guard));
+    process.exit(0);
+  }
+  runStandalone(guard);
+}