uidex 0.5.2 → 0.7.0

package/dist/scan/index.js

@@ -3,7 +3,6 @@ import * as fs from "fs";
 import * as path from "path";
 
 // src/scanner/scan/config.ts
-var DEFAULT_TYPE_MODE = "strict";
 var WELL_KNOWN_FILES = {
   page: "uidex.page.ts",
   feature: "uidex.feature.ts"
@@ -28,11 +27,9 @@ var ALLOWED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "exclude",
   "output",
   "flows",
-  "typeMode",
   "audit",
   "conventions"
 ]);
-var ALLOWED_TYPE_MODES = /* @__PURE__ */ new Set(["strict", "loose"]);
 var ALLOWED_SOURCE_KEYS = /* @__PURE__ */ new Set(["rootDir", "include", "exclude", "prefix"]);
 var ALLOWED_CONVENTIONS_KEYS = /* @__PURE__ */ new Set([
   "primitives",
@@ -45,14 +42,14 @@ var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set(["scopeLeak", "coverage", "acce
 function fail(msg) {
   throw new ConfigError(`Invalid .uidex.json: ${msg}`);
 }
-function assertObject(value, path10) {
+function assertObject(value, path12) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    fail(`${path10} must be an object`);
+    fail(`${path12} must be an object`);
   }
 }
-function assertStringArray(value, path10) {
+function assertStringArray(value, path12) {
   if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
-    fail(`${path10} must be a string[]`);
+    fail(`${path12} must be a string[]`);
   }
 }
 function validateConfig(raw) {
@@ -100,11 +97,6 @@ function validateConfig(raw) {
   }
   if (raw.exclude !== void 0) assertStringArray(raw.exclude, `exclude`);
   if (raw.flows !== void 0) assertStringArray(raw.flows, `flows`);
-  if (raw.typeMode !== void 0) {
-    if (typeof raw.typeMode !== "string" || !ALLOWED_TYPE_MODES.has(raw.typeMode)) {
-      fail(`"typeMode" must be "strict" or "loose"`);
-    }
-  }
   if (raw.audit !== void 0) {
     assertObject(raw.audit, "audit");
     for (const key of Object.keys(raw.audit)) {
@@ -143,7 +135,6 @@ function validateConfig(raw) {
     exclude: raw.exclude,
     output: raw.output,
     flows: raw.flows,
-    typeMode: raw.typeMode ?? DEFAULT_TYPE_MODE,
     audit: raw.audit,
     conventions: raw.conventions
   };
@@ -350,6 +341,90 @@ function* walkDir(root, dir) {
   }
 }
 
+// src/scanner/scan/ast.ts
+import * as path3 from "path";
+import { parseSync } from "oxc-parser";
+function langFor(sourcePath) {
+  switch (path3.extname(sourcePath)) {
+    case ".tsx":
+      return "tsx";
+    case ".ts":
+    case ".mts":
+    case ".cts":
+      return "ts";
+    default:
+      return "jsx";
+  }
+}
+function makeLineAt(content) {
+  const starts = [0];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === "\n") starts.push(i + 1);
+  }
+  return (offset) => {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (starts[mid] <= offset) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo + 1;
+  };
+}
+function parseSource(file) {
+  const lineAt = makeLineAt(file.content);
+  try {
+    const result = parseSync(file.sourcePath, file.content, {
+      lang: langFor(file.sourcePath),
+      sourceType: "module"
+    });
+    return {
+      program: result.program,
+      hasErrors: result.errors.length > 0,
+      comments: result.comments ?? [],
+      lineAt
+    };
+  } catch {
+    return { program: null, hasErrors: true, comments: [], lineAt };
+  }
+}
+function isNode(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+function walkAst(root, visit) {
+  if (!isNode(root)) return;
+  if (visit(root) === false) return;
+  for (const key of Object.keys(root)) {
+    if (key === "type" || key === "start" || key === "end") continue;
+    const value = root[key];
+    if (Array.isArray(value)) {
+      for (const item of value) walkAst(item, visit);
+    } else if (isNode(value)) {
+      walkAst(value, visit);
+    }
+  }
+}
+function unwrapTsExpression(expr) {
+  let node = expr;
+  for (; ; ) {
+    switch (node.type) {
+      case "TSAsExpression":
+      case "TSSatisfiesExpression":
+      case "TSNonNullExpression":
+      case "TSTypeAssertion":
+      case "ParenthesizedExpression": {
+        const inner = node.expression;
+        if (!isNode(inner)) return node;
+        node = inner;
+        break;
+      }
+      default:
+        return node;
+    }
+  }
+}
+
 // src/scanner/scan/extract-uidex-export.ts
 var KIND_DISCRIMINATORS = [
   "page",
@@ -387,6 +462,16 @@ var FALSEABLE = /* @__PURE__ */ new Set([
   "primitive",
   "region"
 ]);
+var SATISFIES_NAMES = {
+  page: "Page",
+  feature: "Feature",
+  primitive: "Primitive",
+  widget: "Widget",
+  region: "Region",
+  flow: "Flow",
+  notFlow: "NotFlow"
+};
+var KNOWN_SATISFIES = new Set(Object.values(SATISFIES_NAMES));
 var ExtractError = class extends Error {
   code;
   hint;
@@ -398,649 +483,285 @@ var ExtractError = class extends Error {
     this.hint = hint;
   }
 };
-function extractUidexExports(file) {
+function extractUidexExports(file, parsed) {
   const exports = [];
   const diagnostics = [];
   const { content, displayPath } = file;
-  for (const header of findExportHeaders(content)) {
-    try {
-      const value = parseExpression(content, header.exprStart);
-      const metadata = buildMetadata(
-        value,
-        displayPath,
-        header.headerPos,
-        diagnostics
-      );
-      exports.push(metadata);
-    } catch (e) {
-      if (e instanceof ExtractError) {
-        diagnostics.push({
-          code: e.code,
-          severity: "error",
-          message: e.message,
-          file: displayPath,
-          line: e.pos.line,
-          hint: e.hint
-        });
-      } else {
-        throw e;
-      }
-    }
-  }
-  return { exports, diagnostics };
-}
-var HEADER_RE = /(?:^|\n)[\t ]*export\s+const\s+uidex\b(?:\s*:\s*[^=\n]+?)?\s*=\s*/g;
-function findExportHeaders(content) {
-  const out2 = [];
-  HEADER_RE.lastIndex = 0;
-  let m;
-  while ((m = HEADER_RE.exec(content)) !== null) {
-    const leadingNewline = m[0].startsWith("\n") ? 1 : 0;
-    const headerOffset = m.index + leadingNewline;
-    const exprStart = m.index + m[0].length;
-    if (isInsideCommentOrString(content, headerOffset)) continue;
-    out2.push({
-      headerPos: posAt(content, headerOffset),
-      exprStart
-    });
-  }
-  return out2;
-}
-function isInsideCommentOrString(content, target) {
-  let i = 0;
-  let inLineComment = false;
-  let inBlockComment = false;
-  let stringDelim = null;
-  let inTemplate = false;
-  let templateDepth = 0;
-  while (i < target) {
-    const c = content[i];
-    const n = content[i + 1];
-    if (inLineComment) {
-      if (c === "\n") inLineComment = false;
-      i++;
-      continue;
-    }
-    if (inBlockComment) {
-      if (c === "*" && n === "/") {
-        inBlockComment = false;
-        i += 2;
-        continue;
-      }
-      i++;
-      continue;
-    }
-    if (stringDelim !== null) {
-      if (c === "\\") {
-        i += 2;
-        continue;
-      }
-      if (c === stringDelim) stringDelim = null;
-      i++;
-      continue;
-    }
-    if (inTemplate) {
-      if (c === "\\") {
-        i += 2;
-        continue;
-      }
-      if (c === "$" && n === "{") {
-        templateDepth++;
-        i += 2;
-        continue;
-      }
-      if (c === "`" && templateDepth === 0) {
-        inTemplate = false;
-        i++;
+  const p2 = parsed ?? parseSource(file);
+  if (p2.program === null) return { exports, diagnostics };
+  for (const stmt of p2.program.body) {
+    if (stmt.type !== "ExportNamedDeclaration") continue;
+    const decl = stmt.declaration;
+    if (!isNode2(decl) || decl.type !== "VariableDeclaration") continue;
+    if (decl.kind !== "const") continue;
+    for (const declarator of decl.declarations ?? []) {
+      const id = declarator.id;
+      if (!id || id.type !== "Identifier" || String(id.name) !== "uidex") {
         continue;
       }
-      if (templateDepth > 0 && c === "}") {
-        templateDepth--;
-        i++;
-        continue;
-      }
-      i++;
-      continue;
-    }
-    if (c === "/" && n === "/") {
-      inLineComment = true;
-      i += 2;
-      continue;
-    }
-    if (c === "/" && n === "*") {
-      inBlockComment = true;
-      i += 2;
-      continue;
-    }
-    if (c === '"' || c === "'") {
-      stringDelim = c;
-      i++;
-      continue;
-    }
-    if (c === "`") {
-      inTemplate = true;
-      i++;
-      continue;
-    }
-    i++;
-  }
-  return inLineComment || inBlockComment || stringDelim !== null || inTemplate;
-}
-var Tokenizer = class {
-  constructor(src, start) {
-    this.src = src;
-    this.pos = start;
-    let line = 1;
-    let lineStart = 0;
-    for (let i = 0; i < start; i++) {
-      if (src[i] === "\n") {
-        line++;
-        lineStart = i + 1;
-      }
-    }
-    this.line = line;
-    this.lineStart = lineStart;
-  }
-  src;
-  pos;
-  line;
-  lineStart;
-  currentPos() {
-    return {
-      offset: this.pos,
-      line: this.line,
-      column: this.pos - this.lineStart + 1
-    };
-  }
-  advance(n = 1) {
-    for (let i = 0; i < n; i++) {
-      if (this.pos < this.src.length && this.src[this.pos] === "\n") {
-        this.line++;
-        this.lineStart = this.pos + 1;
-      }
-      this.pos++;
-    }
-  }
-  skipTrivia() {
-    while (this.pos < this.src.length) {
-      const c = this.src[this.pos];
-      const n = this.src[this.pos + 1];
-      if (c === " " || c === "	" || c === "\r" || c === "\n") {
-        this.advance();
-        continue;
-      }
-      if (c === "/" && n === "/") {
-        while (this.pos < this.src.length && this.src[this.pos] !== "\n") {
-          this.advance();
+      const headerPos = posAt(content, stmt.start, p2);
+      try {
+        const init = declarator.init;
+        if (!isNode2(init)) {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            "`export const uidex` must be assigned an object literal.",
+            headerPos
+          );
         }
-        continue;
-      }
-      if (c === "/" && n === "*") {
-        this.advance(2);
-        while (this.pos < this.src.length) {
-          if (this.src[this.pos] === "*" && this.src[this.pos + 1] === "/") {
-            this.advance(2);
-            break;
-          }
-          this.advance();
+        const value = toLitValue(unwrapTsExpression(init), content, p2);
+        const metadata = buildMetadata(
+          value,
+          displayPath,
+          file.sourcePath,
+          headerPos,
+          diagnostics
+        );
+        metadata.span = statementSpan(stmt, content);
+        checkSatisfies(init, metadata, displayPath, p2, diagnostics);
+        exports.push(metadata);
+      } catch (e) {
+        if (e instanceof ExtractError) {
+          diagnostics.push({
+            code: e.code,
+            severity: "error",
+            message: e.message,
+            file: displayPath,
+            line: e.pos.line,
+            hint: e.hint
+          });
+        } else {
+          throw e;
         }
-        continue;
       }
-      break;
-    }
-  }
-  next() {
-    this.skipTrivia();
-    if (this.pos >= this.src.length) {
-      return { kind: "eof", value: "", pos: this.currentPos(), end: this.pos };
-    }
-    const pos = this.currentPos();
-    const c = this.src[this.pos];
-    switch (c) {
-      case "{":
-        this.advance();
-        return { kind: "lbrace", value: c, pos, end: this.pos };
-      case "}":
-        this.advance();
-        return { kind: "rbrace", value: c, pos, end: this.pos };
-      case "[":
-        this.advance();
-        return { kind: "lbracket", value: c, pos, end: this.pos };
-      case "]":
-        this.advance();
-        return { kind: "rbracket", value: c, pos, end: this.pos };
-      case "(":
-        this.advance();
-        return { kind: "lparen", value: c, pos, end: this.pos };
-      case ")":
-        this.advance();
-        return { kind: "rparen", value: c, pos, end: this.pos };
-      case ",":
-        this.advance();
-        return { kind: "comma", value: c, pos, end: this.pos };
-      case ":":
-        this.advance();
-        return { kind: "colon", value: c, pos, end: this.pos };
-    }
-    if (c === "." && this.src[this.pos + 1] === "." && this.src[this.pos + 2] === ".") {
-      this.advance(3);
-      return { kind: "spread", value: "...", pos, end: this.pos };
-    }
-    if (c === '"' || c === "'") {
-      return this.readString(pos, c);
-    }
-    if (c === "`") {
-      return this.readTemplate(pos);
-    }
-    if (isDigit(c) || c === "-" && isDigit(this.src[this.pos + 1])) {
-      return this.readNumber(pos);
     }
-    if (isIdentStart(c)) {
-      return this.readIdent(pos);
-    }
-    this.advance();
-    return { kind: "punct", value: c, pos, end: this.pos };
   }
-  readString(pos, delim) {
-    this.advance();
-    let value = "";
-    while (this.pos < this.src.length) {
-      const c = this.src[this.pos];
-      if (c === "\\") {
-        const esc = this.src[this.pos + 1];
-        this.advance(2);
-        value += decodeEscape(esc);
-        continue;
-      }
-      if (c === delim) {
-        this.advance();
-        return { kind: "string", value, pos, end: this.pos };
-      }
-      if (c === "\n") {
-        return { kind: "punct", value: delim, pos, end: this.pos };
-      }
-      value += c;
-      this.advance();
-    }
-    return { kind: "punct", value: delim, pos, end: this.pos };
-  }
-  readTemplate(pos) {
-    this.advance();
-    let value = "";
-    let hasExpression = false;
-    while (this.pos < this.src.length) {
-      const c = this.src[this.pos];
-      const n = this.src[this.pos + 1];
-      if (c === "\\") {
-        const esc = this.src[this.pos + 1];
-        this.advance(2);
-        value += decodeEscape(esc);
-        continue;
-      }
-      if (c === "$" && n === "{") {
-        hasExpression = true;
-        this.advance(2);
-        let depth = 1;
-        while (this.pos < this.src.length && depth > 0) {
-          const ch = this.src[this.pos];
-          if (ch === "{") depth++;
-          else if (ch === "}") depth--;
-          this.advance();
+  return { exports, diagnostics };
+}
+function toLitValue(node, content, p2) {
+  const unwrapped = unwrapTsExpression(node);
+  const pos = posAt(content, unwrapped.start, p2);
+  const span = { start: unwrapped.start, end: unwrapped.end };
+  switch (unwrapped.type) {
+    case "Literal": {
+      const v = unwrapped.value;
+      if (typeof v === "string") return { kind: "string", value: v, pos, span };
+      if (typeof v === "number") {
+        if (!Number.isFinite(v)) {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            `Invalid numeric literal in \`export const uidex\`.`,
+            pos
+          );
         }
-        continue;
+        return { kind: "number", value: v, pos, span };
       }
-      if (c === "`") {
-        this.advance();
-        if (hasExpression) {
-          return { kind: "template", value, pos, end: this.pos };
-        }
-        return { kind: "string", value, pos, end: this.pos };
+      if (typeof v === "boolean") {
+        return { kind: "boolean", value: v, pos, span };
       }
-      value += c;
-      this.advance();
-    }
-    return { kind: "template", value, pos, end: this.pos };
-  }
-  readNumber(pos) {
-    const start = this.pos;
-    if (this.src[this.pos] === "-") this.advance();
-    while (this.pos < this.src.length && isDigit(this.src[this.pos])) {
-      this.advance();
-    }
-    if (this.src[this.pos] === ".") {
-      this.advance();
-      while (this.pos < this.src.length && isDigit(this.src[this.pos])) {
-        this.advance();
+      if (v === null && unwrapped.raw === "null") {
+        return { kind: "null", pos, span };
       }
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Unsupported literal in \`export const uidex\`; only strings, numbers, booleans, and null are allowed.`,
+        pos
+      );
     }
-    if (this.src[this.pos] === "e" || this.src[this.pos] === "E") {
-      this.advance();
-      if (this.src[this.pos] === "+" || this.src[this.pos] === "-") {
-        this.advance();
+    case "UnaryExpression": {
+      const arg = unwrapped.argument;
+      if (unwrapped.operator === "-" && isNode2(arg) && arg.type === "Literal" && typeof arg.value === "number") {
+        return { kind: "number", value: -arg.value, pos, span };
       }
-      while (this.pos < this.src.length && isDigit(this.src[this.pos])) {
-        this.advance();
-      }
-    }
-    const value = this.src.slice(start, this.pos);
-    return { kind: "number", value, pos, end: this.pos };
-  }
-  readIdent(pos) {
-    const start = this.pos;
-    while (this.pos < this.src.length && isIdentPart(this.src[this.pos])) {
-      this.advance();
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Unary expressions are not allowed in `export const uidex`.",
+        pos
+      );
     }
-    const value = this.src.slice(start, this.pos);
-    return { kind: "ident", value, pos, end: this.pos };
-  }
-};
-function isDigit(c) {
-  return c !== void 0 && c >= "0" && c <= "9";
-}
-function isIdentStart(c) {
-  if (c === void 0) return false;
-  return c >= "a" && c <= "z" || c >= "A" && c <= "Z" || c === "_" || c === "$";
-}
-function isIdentPart(c) {
-  return isIdentStart(c) || isDigit(c);
-}
-function decodeEscape(esc) {
-  switch (esc) {
-    case "n":
-      return "\n";
-    case "t":
-      return "	";
-    case "r":
-      return "\r";
-    case "\\":
-      return "\\";
-    case "'":
-      return "'";
-    case '"':
-      return '"';
-    case "`":
-      return "`";
-    case "0":
-      return "\0";
-    case "b":
-      return "\b";
-    case "f":
-      return "\f";
-    case "v":
-      return "\v";
-    default:
-      return esc ?? "";
-  }
-}
-function parseExpression(content, start) {
-  const tokenizer = new Tokenizer(content, start);
-  const parser = new Parser(tokenizer);
-  const value = parser.parseValue();
-  parser.consumeTrailingAssertions();
-  return value;
-}
-var Parser = class {
-  constructor(tok) {
-    this.tok = tok;
-  }
-  tok;
-  lookahead = null;
-  peek() {
-    if (this.lookahead === null) this.lookahead = this.tok.next();
-    return this.lookahead;
-  }
-  consume() {
-    const t = this.peek();
-    this.lookahead = null;
-    return t;
-  }
-  parseValue() {
-    const t = this.peek();
-    switch (t.kind) {
-      case "lbrace":
-        return this.parseObject();
-      case "lbracket":
-        return this.parseArray();
-      case "string":
-        this.consume();
-        return { kind: "string", value: t.value, pos: t.pos };
-      case "template":
+    case "TemplateLiteral": {
+      const expressions = unwrapped.expressions ?? [];
+      if (expressions.length > 0) {
         throw new ExtractError(
           "uidex-export-invalid-literal",
           "Template literal with expression parts is not allowed in `export const uidex`; use a plain string literal.",
-          t.pos
-        );
-      case "number": {
-        this.consume();
-        const n = Number(t.value);
-        if (!Number.isFinite(n)) {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            `Invalid numeric literal "${t.value}" in \`export const uidex\`.`,
-            t.pos
-          );
-        }
-        return { kind: "number", value: n, pos: t.pos };
-      }
-      case "ident":
-        if (t.value === "true" || t.value === "false") {
-          this.consume();
-          return {
-            kind: "boolean",
-            value: t.value === "true",
-            pos: t.pos
-          };
-        }
-        if (t.value === "null") {
-          this.consume();
-          return { kind: "null", pos: t.pos };
-        }
-        if (t.value === "undefined") {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            "`undefined` is not allowed as a value in `export const uidex`; omit the field instead.",
-            t.pos
-          );
-        }
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          `Identifier reference "${t.value}" is not allowed in \`export const uidex\`; the right-hand side must be a plain literal.`,
-          t.pos
-        );
-      case "spread":
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Spread (`...`) is not allowed in `export const uidex`; the right-hand side must be a plain literal.",
-          t.pos
-        );
-      case "lparen":
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Parenthesised or grouped expressions are not allowed in `export const uidex`.",
-          t.pos
-        );
-      case "punct":
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          `Unexpected token "${t.value}" in \`export const uidex\`.`,
-          t.pos
-        );
-      case "eof":
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Expected a value for `export const uidex` but reached end of file.",
-          t.pos
-        );
-      default:
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          `Unexpected token in \`export const uidex\`.`,
-          t.pos
+          pos
         );
-    }
-  }
-  parseObject() {
-    const open = this.consume();
-    const entries = [];
-    const seen = /* @__PURE__ */ new Set();
-    while (true) {
-      const t = this.peek();
-      if (t.kind === "rbrace") {
-        this.consume();
-        break;
       }
-      if (t.kind === "spread") {
+      const quasis = unwrapped.quasis ?? [];
+      const cooked = quasis[0]?.value?.cooked ?? "";
+      return { kind: "string", value: cooked, pos, span };
+    }
+    case "Identifier": {
+      const name = String(unwrapped.name);
+      if (name === "undefined") {
         throw new ExtractError(
           "uidex-export-invalid-literal",
-          "Spread (`...`) is not allowed inside `export const uidex`.",
-          t.pos
+          "`undefined` is not allowed as a value in `export const uidex`; omit the field instead.",
+          pos
         );
       }
-      if (t.kind === "lbracket") {
-        this.consume();
-        const keyTok = this.peek();
-        if (keyTok.kind !== "string") {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            "Computed property keys must be string literals in `export const uidex`.",
-            keyTok.pos
-          );
-        }
-        this.consume();
-        const close = this.peek();
-        if (close.kind !== "rbracket") {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            "Expected `]` after computed property key.",
-            close.pos
-          );
-        }
-        this.consume();
-        const colon = this.peek();
-        if (colon.kind !== "colon") {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            "Expected `:` after computed property key.",
-            colon.pos
-          );
-        }
-        this.consume();
-        const value = this.parseValue();
-        this.recordEntry(entries, seen, keyTok.value, value, keyTok.pos);
-      } else if (t.kind === "ident" || t.kind === "string") {
-        const keyTok = this.consume();
-        const next = this.peek();
-        if (next.kind === "colon") {
-          this.consume();
-          const value = this.parseValue();
-          this.recordEntry(entries, seen, keyTok.value, value, keyTok.pos);
-        } else {
-          throw new ExtractError(
-            "uidex-export-invalid-literal",
-            keyTok.kind === "ident" ? `Shorthand property "${keyTok.value}" is not allowed; write "${keyTok.value}: ..." with a literal value.` : "Expected `:` after property key.",
-            keyTok.pos
-          );
-        }
-      } else if (t.kind === "number") {
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Numeric property keys are not allowed in `export const uidex`.",
-          t.pos
-        );
-      } else {
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Identifier reference "${name}" is not allowed in \`export const uidex\`; the right-hand side must be a plain literal.`,
+        pos
+      );
+    }
+    case "ObjectExpression":
+      return objectLit(unwrapped, content, p2, pos, span);
+    case "ArrayExpression":
+      return arrayLit(unwrapped, content, p2, pos, span);
+    case "SpreadElement":
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Spread (`...`) is not allowed in `export const uidex`; the right-hand side must be a plain literal.",
+        pos
+      );
+    case "CallExpression":
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Function calls are not allowed in `export const uidex`; the right-hand side must be a plain literal.",
+        pos
+      );
+    case "ConditionalExpression":
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Conditional expressions are not allowed in `export const uidex`; the right-hand side must be a plain literal.",
+        pos
+      );
+    default:
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Computed expressions are not allowed in \`export const uidex\`; the right-hand side must be a plain literal.`,
+        pos
+      );
+  }
+}
+function objectLit(node, content, p2, pos, span) {
+  const entries = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const prop of node.properties ?? []) {
+    if (prop.type === "SpreadElement") {
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Spread (`...`) is not allowed inside `export const uidex`.",
+        posAt(content, prop.start, p2)
+      );
+    }
+    if (prop.type !== "Property") {
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Unexpected member inside `export const uidex` object.",
+        posAt(content, prop.start, p2)
+      );
+    }
+    const keyNode = prop.key;
+    const keyPos = posAt(content, keyNode.start, p2);
+    if (prop.shorthand) {
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Shorthand property "${String(keyNode.name)}" is not allowed; write "${String(keyNode.name)}: ..." with a literal value.`,
+        keyPos
+      );
+    }
+    let key;
+    if (prop.computed) {
+      if (keyNode.type !== "Literal" || typeof keyNode.value !== "string") {
         throw new ExtractError(
           "uidex-export-invalid-literal",
-          `Unexpected token "${t.value}" inside object.`,
-          t.pos
+          "Computed property keys must be string literals in `export const uidex`.",
+          keyPos
         );
       }
-      const after = this.peek();
-      if (after.kind === "comma") {
-        this.consume();
-        continue;
-      }
-      if (after.kind === "rbrace") {
-        this.consume();
-        break;
-      }
+      key = keyNode.value;
+    } else if (keyNode.type === "Identifier") {
+      key = String(keyNode.name);
+    } else if (keyNode.type === "Literal" && typeof keyNode.value === "string") {
+      key = keyNode.value;
+    } else {
       throw new ExtractError(
         "uidex-export-invalid-literal",
-        `Expected \`,\` or \`}\`, got "${after.value}".`,
-        after.pos
+        "Numeric property keys are not allowed in `export const uidex`.",
+        keyPos
       );
     }
-    return { kind: "object", entries, pos: open.pos };
-  }
-  recordEntry(entries, seen, key, value, pos) {
     if (seen.has(key)) {
       throw new ExtractError(
         "uidex-export-duplicate-field",
         `Duplicate field "${key}" in \`export const uidex\`.`,
-        pos
+        keyPos
       );
     }
     seen.add(key);
-    entries.push([key, value]);
-  }
-  parseArray() {
-    const open = this.consume();
-    const items = [];
-    while (true) {
-      const t = this.peek();
-      if (t.kind === "rbracket") {
-        this.consume();
-        break;
-      }
-      if (t.kind === "spread") {
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Spread (`...`) is not allowed inside `export const uidex`.",
-          t.pos
-        );
-      }
-      const value = this.parseValue();
-      if (value.kind === "object") {
-      }
-      items.push(value);
-      const after = this.peek();
-      if (after.kind === "comma") {
-        this.consume();
-        continue;
-      }
-      if (after.kind === "rbracket") {
-        this.consume();
-        break;
-      }
+    const value = toLitValue(prop.value, content, p2);
+    entries.push({
+      key,
+      value,
+      keyPos,
+      span: removalSpan(content, prop.start, prop.end)
+    });
+  }
+  return { kind: "object", entries, pos, span };
+}
+function arrayLit(node, content, p2, pos, span) {
+  const items = [];
+  for (const el of node.elements ?? []) {
+    if (el === null) {
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        "Array holes are not allowed in `export const uidex`.",
+        pos
+      );
+    }
+    if (el.type === "SpreadElement") {
       throw new ExtractError(
         "uidex-export-invalid-literal",
-        `Expected \`,\` or \`]\`, got "${after.value}".`,
-        after.pos
+        "Spread (`...`) is not allowed inside `export const uidex`.",
+        posAt(content, el.start, p2)
       );
     }
-    return { kind: "array", items, pos: open.pos };
+    items.push(toLitValue(el, content, p2));
   }
-  consumeTrailingAssertions() {
-    const first = this.peek();
-    if (first.kind === "ident" && first.value === "as") {
-      this.consume();
-      const next = this.peek();
-      if (next.kind === "ident" && next.value === "const") {
-        this.consume();
-      } else {
-        throw new ExtractError(
-          "uidex-export-invalid-literal",
-          "Only `as const` is allowed after the `export const uidex` value.",
-          next.pos
-        );
-      }
+  return { kind: "array", items, pos, span };
+}
+function checkSatisfies(init, metadata, file, p2, diagnostics) {
+  let node = init;
+  let satisfiesType;
+  while (isNode2(node)) {
+    if (node.type === "TSSatisfiesExpression") {
+      satisfiesType = node.typeAnnotation;
+      break;
     }
-    const maybeSatisfies = this.peek();
-    if (maybeSatisfies.kind === "ident" && maybeSatisfies.value === "satisfies") {
-      return;
+    if (node.type === "TSAsExpression" || node.type === "TSNonNullExpression" || node.type === "TSTypeAssertion" || node.type === "ParenthesizedExpression") {
+      node = node.expression;
+      continue;
     }
+    break;
   }
-};
-function buildMetadata(value, file, headerPos, diagnostics) {
+  if (!isNode2(satisfiesType) || satisfiesType.type !== "TSTypeReference") return;
+  const typeName = satisfiesType.typeName;
+  if (!isNode2(typeName) || typeName.type !== "TSQualifiedName") return;
+  const left = typeName.left;
+  const right = typeName.right;
+  if (!isNode2(left) || left.type !== "Identifier" || left.name !== "Uidex") {
+    return;
+  }
+  if (!isNode2(right) || right.type !== "Identifier") return;
+  const actual = String(right.name);
+  if (!KNOWN_SATISFIES.has(actual)) return;
+  const discriminator = metadata.notFlow ? "notFlow" : metadata.kind;
+  const expected = SATISFIES_NAMES[discriminator];
+  if (actual === expected) return;
+  diagnostics.push({
+    code: "uidex-export-satisfies-mismatch",
+    severity: "warning",
+    message: `\`export const uidex\` declares kind "${discriminator}" but is annotated \`satisfies Uidex.${actual}\`; expected \`Uidex.${expected}\`.`,
+    file,
+    line: p2.lineAt(satisfiesType.start),
+    hint: `Change the annotation to \`satisfies Uidex.${expected}\` or fix the kind discriminator.`
+  });
+}
+function buildMetadata(value, file, sourcePath, headerPos, diagnostics) {
   if (value.kind !== "object") {
     throw new ExtractError(
       "uidex-export-invalid-literal",
@@ -1049,7 +770,7 @@ function buildMetadata(value, file, headerPos, diagnostics) {
     );
   }
   const byKey = /* @__PURE__ */ new Map();
-  for (const [k, v] of value.entries) byKey.set(k, v);
+  for (const entry of value.entries) byKey.set(entry.key, entry);
   const presentKinds = KIND_DISCRIMINATORS.filter(
     (k) => byKey.has(k)
   );
@@ -1072,49 +793,58 @@ function buildMetadata(value, file, headerPos, diagnostics) {
   const discriminator = presentKinds[0];
   const kind = discriminator === "notFlow" ? "flow" : discriminator;
   const allowed = ALLOWED_FIELDS[kind];
-  for (const [k] of value.entries) {
-    if (!allowed.has(k)) {
-      const fieldVal = byKey.get(k);
+  for (const entry of value.entries) {
+    if (!allowed.has(entry.key)) {
       throw new ExtractError(
         "uidex-export-unknown-field",
-        `Unknown field "${k}" in \`export const uidex\` for kind "${kind}". Allowed: ${Array.from(
+        `Unknown field "${entry.key}" in \`export const uidex\` for kind "${kind}". Allowed: ${Array.from(
           allowed
         ).sort().join(", ")}.`,
-        fieldVal.pos
+        entry.value.pos
       );
     }
   }
   const idField = discriminator === "notFlow" ? "flow" : discriminator;
-  const idValue = byKey.get(discriminator);
+  const idValue = byKey.get(discriminator).value;
   let id;
   if (discriminator === "notFlow") {
-    const v = idValue;
-    if (v.kind !== "boolean" || v.value !== true) {
+    if (idValue.kind !== "boolean" || idValue.value !== true) {
       throw new ExtractError(
         "uidex-export-invalid-field",
         "`notFlow` must be `true`.",
-        v.pos
+        idValue.pos
       );
     }
     id = false;
   } else {
     id = readIdField(idValue, kind, idField);
   }
-  const acceptance = readStringArrayField(byKey, "acceptance");
+  const acceptance = readStringArrayField(byKey, "acceptance")?.values;
   const description = readStringField(byKey, "description");
   const name = readStringField(byKey, "name");
   if (name === "") {
-    const pos = byKey.get("name").pos;
+    const entry = byKey.get("name");
     diagnostics.push({
       code: "uidex-export-empty-name",
       severity: "info",
       message: "`name` is an empty string; treating as unset.",
       file,
-      line: pos.line
+      line: entry.value.pos.line,
+      fix: {
+        description: "Remove the empty `name` field",
+        edits: [
+          {
+            path: sourcePath,
+            start: entry.span.start,
+            end: entry.span.end,
+            replacement: ""
+          }
+        ]
+      }
     });
   }
-  const features = kind === "page" || kind === "feature" ? readStringArrayField(byKey, "features") : void 0;
-  const widgets = kind === "page" ? readStringArrayField(byKey, "widgets") : void 0;
+  const featuresField = kind === "page" || kind === "feature" ? readStringArrayField(byKey, "features") : void 0;
+  const widgetsField = kind === "page" ? readStringArrayField(byKey, "widgets") : void 0;
   const notFlow = kind === "flow" && discriminator === "notFlow" ? true : void 0;
   const metadata = {
     source: "ts-export",
@@ -1129,9 +859,21 @@ function buildMetadata(value, file, headerPos, diagnostics) {
   if (name) metadata.name = name;
   if (acceptance) metadata.acceptance = acceptance;
   if (description) metadata.description = description;
-  if (features) metadata.features = features;
-  if (widgets) metadata.widgets = widgets;
+  if (featuresField) {
+    metadata.features = featuresField.values;
+    metadata.featureSpans = featuresField.spans;
+  }
+  if (widgetsField) {
+    metadata.widgets = widgetsField.values;
+    metadata.widgetSpans = widgetsField.spans;
+  }
   if (notFlow) metadata.notFlow = true;
+  if (typeof id === "string" && idValue.kind === "string") {
+    metadata.idSpan = idValue.span;
+  }
+  const fieldSpans = {};
+  for (const entry of value.entries) fieldSpans[entry.key] = entry.span;
+  metadata.fieldSpans = fieldSpans;
   return metadata;
 }
 function readIdField(value, kind, fieldName) {
@@ -1162,29 +904,30 @@ function readIdField(value, kind, fieldName) {
   );
 }
 function readStringField(byKey, name) {
-  const v = byKey.get(name);
-  if (!v) return void 0;
-  if (v.kind !== "string") {
+  const entry = byKey.get(name);
+  if (!entry) return void 0;
+  if (entry.value.kind !== "string") {
     throw new ExtractError(
       "uidex-export-invalid-field",
       `\`${name}\` must be a string.`,
-      v.pos
+      entry.value.pos
     );
   }
-  return v.value;
+  return entry.value.value;
 }
 function readStringArrayField(byKey, name) {
-  const v = byKey.get(name);
-  if (!v) return void 0;
-  if (v.kind !== "array") {
+  const entry = byKey.get(name);
+  if (!entry) return void 0;
+  if (entry.value.kind !== "array") {
     throw new ExtractError(
       "uidex-export-invalid-field",
       `\`${name}\` must be an array of strings.`,
-      v.pos
+      entry.value.pos
     );
   }
-  const out2 = [];
-  for (const item of v.items) {
+  const values = [];
+  const spans = [];
+  for (const item of entry.value.items) {
     if (item.kind !== "string") {
       throw new ExtractError(
         "uidex-export-invalid-field",
@@ -1192,316 +935,526 @@ function readStringArrayField(byKey, name) {
         item.pos
       );
     }
-    out2.push(item.value);
+    values.push(item.value);
+    spans.push(item.span);
   }
-  return out2;
+  return { values, spans };
 }
-function posAt(content, offset) {
-  let line = 1;
-  let lineStart = 0;
-  for (let i = 0; i < offset && i < content.length; i++) {
-    if (content[i] === "\n") {
-      line++;
-      lineStart = i + 1;
-    }
-  }
-  return { offset, line, column: offset - lineStart + 1 };
+function posAt(content, offset, p2) {
+  const lineStart = content.lastIndexOf("\n", offset - 1) + 1;
+  return { offset, line: p2.lineAt(offset), column: offset - lineStart + 1 };
+}
+function removalSpan(content, start, end) {
+  let e = end;
+  while (e < content.length && /[ \t]/.test(content[e])) e++;
+  if (content[e] === ",") return { start, end: e + 1 };
+  let s = start;
+  while (s > 0 && /[\s]/.test(content[s - 1])) s--;
+  if (content[s - 1] === ",") return { start: s - 1, end };
+  return { start, end };
+}
+function statementSpan(stmt, content) {
+  let end = stmt.end;
+  while (end < content.length && /[ \t]/.test(content[end])) end++;
+  if (content[end] === ";") end++;
+  while (end < content.length && /[ \t]/.test(content[end])) end++;
+  if (content[end] === "\r") end++;
+  if (content[end] === "\n") end++;
+  return { start: stmt.start, end };
+}
+function isNode2(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
 }
 
-// src/scanner/scan/jsx-ancestry.ts
-var DATA_ATTR_RE = /\bdata-uidex(?:-(region|widget|primitive))?\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
-function parseDataAttrs(tagSource) {
-  if (!tagSource.includes("data-uidex")) return [];
-  const out2 = [];
-  for (const m of tagSource.matchAll(DATA_ATTR_RE)) {
-    const kind = m[1] ?? "element";
-    const id = m[2] ?? m[3];
-    if (id) out2.push({ kind, id });
-  }
-  return out2;
+// src/scanner/scan/flow-facts.ts
+function collectFlowFacts(parsed, content) {
+  if (parsed.program === null || !content.includes("test.describe")) {
+    return [];
+  }
+  const facts = [];
+  walkAst(parsed.program, (node) => {
+    if (node.type !== "CallExpression") return void 0;
+    const fact = readTaggedDescribe(node, parsed);
+    if (fact) facts.push(fact);
+    return void 0;
+  });
+  return facts;
 }
-function collectJSXAncestry(content) {
-  if (!content.includes("data-uidex")) return [];
-  const out2 = [];
-  const ancestors = [];
-  const stack = [];
-  const N = content.length;
-  let i = 0;
-  let line = 1;
-  const advanceLines = (from, to) => {
-    for (let k = from; k < to; k++) {
-      if (content.charCodeAt(k) === 10) line++;
-    }
+function readTaggedDescribe(call, parsed) {
+  const callee = call.callee;
+  if (!callee || callee.type !== "MemberExpression" || !isIdentifier(callee.object, "test") || !isIdentifier(callee.property, "describe")) {
+    return null;
+  }
+  const args = call.arguments ?? [];
+  const title = stringLiteralValue(args[0]);
+  if (title === null) return null;
+  if (!hasFlowTag(args[1])) return null;
+  const body = args[2];
+  const { calls, dynamicCalls } = body ? collectUidexCalls(body, parsed) : { calls: [], dynamicCalls: [] };
+  return {
+    title,
+    line: parsed.lineAt(call.start),
+    calls,
+    ...dynamicCalls.length > 0 ? { dynamicCalls } : {}
   };
-  while (i < N) {
-    const c = content[i];
-    if (c === "\n") {
-      line++;
-      i++;
-      continue;
-    }
-    if (c === "/" && content[i + 1] === "/") {
-      while (i < N && content[i] !== "\n") i++;
-      continue;
-    }
-    if (c === "/" && content[i + 1] === "*") {
-      const end = content.indexOf("*/", i + 2);
-      const next = end === -1 ? N : end + 2;
-      advanceLines(i, next);
-      i = next;
-      continue;
-    }
-    if (c === '"' || c === "'") {
-      const next = skipString(content, i, c);
-      advanceLines(i, next);
-      i = next;
-      continue;
+}
+function hasFlowTag(node) {
+  if (!node || node.type !== "ObjectExpression") return false;
+  for (const prop of node.properties ?? []) {
+    if (prop.type !== "Property") continue;
+    const key = prop.key;
+    const keyName = key?.type === "Identifier" ? String(key.name) : key?.type === "Literal" ? String(key.value) : null;
+    if (keyName !== "tag") continue;
+    const value = prop.value;
+    if (!value) return false;
+    if (stringLiteralValue(value) === "@uidex:flow") return true;
+    if (value.type === "ArrayExpression") {
+      for (const el of value.elements ?? []) {
+        if (el && stringLiteralValue(el) === "@uidex:flow") return true;
+      }
     }
-    if (c === "`") {
-      const next = skipTemplate(content, i);
-      advanceLines(i, next);
-      i = next;
-      continue;
+    return false;
+  }
+  return false;
+}
+function collectUidexCalls(body, parsed) {
+  const calls = [];
+  const dynamicCalls = [];
+  const claimed = /* @__PURE__ */ new Set();
+  const record = (node, action) => {
+    if (claimed.has(node)) return;
+    claimed.add(node);
+    const resolved = uidexCallId(node);
+    if (resolved === null) {
+      dynamicCalls.push({ line: parsed.lineAt(node.start) });
+      return;
     }
-    if (c === "<") {
-      const nextCh = content[i + 1];
-      if (nextCh === "/") {
-        const end = content.indexOf(">", i);
-        if (end === -1) break;
-        const tagName = content.slice(i + 2, end).match(/^\s*([\w.-]*)/)?.[1] ?? "";
-        if (tagName) {
-          for (let k = stack.length - 1; k >= 0; k--) {
-            if (stack[k].tagName === tagName) {
-              for (let j = stack.length - 1; j >= k; j--) {
-                ancestors.length -= stack[j].pushed;
-              }
-              stack.length = k;
-              break;
-            }
-          }
-        }
-        advanceLines(i, end + 1);
-        i = end + 1;
-        continue;
-      }
-      if (nextCh && /[A-Za-z_]/.test(nextCh)) {
-        const end = findTagEnd(content, i + 1);
-        if (end === -1) break;
-        const tagSource = content.slice(i, end + 1);
-        const tagName = tagSource.match(/^<\s*([\w.-]*)/)?.[1] ?? "";
-        const isSelf = content[end - 1] === "/";
-        if (tagName) {
-          const attrs = parseDataAttrs(tagSource);
-          if (attrs.length > 0) {
-            const snapshot = ancestors.slice();
-            for (const a of attrs) {
-              out2.push({ kind: a.kind, id: a.id, line, ancestors: snapshot });
-            }
-          }
-          if (!isSelf) {
-            for (const a of attrs) ancestors.push(a);
-            stack.push({ tagName, pushed: attrs.length });
-          }
-        }
-        advanceLines(i, end + 1);
-        i = end + 1;
+    calls.push({
+      id: resolved.id,
+      ...action ? { action } : {},
+      line: parsed.lineAt(node.start),
+      span: resolved.span
+    });
+  };
+  walkAst(body, (node) => {
+    if (node.type !== "CallExpression") return void 0;
+    const callee = node.callee;
+    if (callee?.type === "MemberExpression") {
+      const inner = callee.object;
+      if (inner && isUidexCall(inner)) {
+        const property = callee.property;
+        const action = property?.type === "Identifier" ? String(property.name) : void 0;
+        record(inner, action);
+      }
+      return void 0;
+    }
+    if (isUidexCall(node)) record(node);
+    return void 0;
+  });
+  return { calls, dynamicCalls };
+}
+function isUidexCall(node) {
+  if (node.type !== "CallExpression") return false;
+  if (!isIdentifier(node.callee, "uidex")) return false;
+  return (node.arguments ?? []).length >= 1;
+}
+function uidexCallId(node) {
+  const args = node.arguments ?? [];
+  const arg = args[0];
+  const id = stringLiteralValue(arg);
+  if (id === null) return null;
+  return { id, span: { start: arg.start, end: arg.end } };
+}
+function stringLiteralValue(node) {
+  if (!node) return null;
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value.length > 0 ? node.value : null;
+  }
+  if (node.type === "TemplateLiteral") {
+    const expressions = node.expressions ?? [];
+    if (expressions.length > 0) return null;
+    const quasis = node.quasis ?? [];
+    const cooked = quasis[0]?.value?.cooked;
+    return cooked && cooked.length > 0 ? cooked : null;
+  }
+  return null;
+}
+function isIdentifier(node, name) {
+  return typeof node === "object" && node !== null && node.type === "Identifier" && String(node.name) === name;
+}
+
+// src/scanner/scan/jsx-ancestry.ts
+var ATTR_NAME_RE = /^data-uidex(?:-(region|widget|primitive))?$/;
+var INTERACTIVE_TAGS = /* @__PURE__ */ new Set(["button", "a", "input", "select", "textarea"]);
+var LANDMARK_TAGS = /* @__PURE__ */ new Set(["header", "nav", "main", "aside", "footer"]);
+function attrKind(node) {
+  const name = node.name;
+  if (!name || name.type !== "JSXIdentifier") return null;
+  const m = ATTR_NAME_RE.exec(String(name.name));
+  if (!m) return null;
+  return m[1] ?? "element";
+}
+function collectConstStrings(program) {
+  const consts = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  walkAst(program, (node) => {
+    if (node.type !== "VariableDeclaration" || node.kind !== "const") {
+      return void 0;
+    }
+    for (const decl of node.declarations ?? []) {
+      const id = decl.id;
+      if (!id || id.type !== "Identifier") continue;
+      const name = String(id.name);
+      if (seen.has(name)) {
+        consts.delete(name);
         continue;
       }
+      seen.add(name);
+      const init = decl.init;
+      if (!init) continue;
+      const value = staticString(unwrapTsExpression(init));
+      if (value !== null) consts.set(name, value);
     }
-    i++;
-  }
-  return out2;
+    return void 0;
+  });
+  return consts;
 }
-function skipString(content, start, quote) {
-  const N = content.length;
-  let i = start + 1;
-  while (i < N) {
-    const c = content[i];
-    if (c === "\\") {
-      i += 2;
-      continue;
-    }
-    if (c === quote) return i + 1;
-    i++;
+function staticString(node) {
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value;
   }
-  return N;
+  if (node.type === "TemplateLiteral") {
+    const expressions = node.expressions ?? [];
+    if (expressions.length > 0) return null;
+    const quasis = node.quasis ?? [];
+    return quasis[0]?.value?.cooked ?? "";
+  }
+  return null;
 }
-function skipTemplate(content, start) {
-  const N = content.length;
-  let i = start + 1;
-  while (i < N) {
-    const c = content[i];
-    if (c === "\\") {
-      i += 2;
-      continue;
-    }
-    if (c === "`") return i + 1;
-    if (c === "$" && content[i + 1] === "{") {
-      i += 2;
-      let depth = 1;
-      while (i < N && depth > 0) {
-        const cj = content[i];
-        if (cj === '"' || cj === "'") {
-          i = skipString(content, i, cj);
-          continue;
-        }
-        if (cj === "`") {
-          i = skipTemplate(content, i);
-          continue;
+var UNRESOLVED = { resolved: false };
+function evalIdExpression(expr, consts) {
+  const node = unwrapTsExpression(expr);
+  const literal = staticString(node);
+  if (literal !== null) {
+    return literal.length > 0 ? { resolved: true, ids: [literal] } : UNRESOLVED;
+  }
+  if (node.type === "TemplateLiteral") {
+    const quasis = node.quasis ?? [];
+    const expressions = node.expressions ?? [];
+    let out2 = "";
+    for (let i = 0; i < quasis.length; i++) {
+      out2 += quasis[i].value?.cooked ?? "";
+      if (i < expressions.length) {
+        const part = evalIdExpression(expressions[i], consts);
+        out2 += part.resolved && part.ids.length === 1 ? part.ids[0] : "*";
+      }
+    }
+    out2 = out2.replace(/\*{2,}/g, "*");
+    if (!out2.includes("*")) {
+      return out2.length > 0 ? { resolved: true, ids: [out2] } : UNRESOLVED;
+    }
+    return out2.replace(/\*/g, "").length > 0 ? { resolved: true, ids: [out2] } : UNRESOLVED;
+  }
+  if (node.type === "Identifier") {
+    const value = consts.get(String(node.name));
+    return value !== void 0 && value.length > 0 ? { resolved: true, ids: [value] } : UNRESOLVED;
+  }
+  if (node.type === "ConditionalExpression") {
+    const left = evalIdExpression(node.consequent, consts);
+    const right = evalIdExpression(node.alternate, consts);
+    if (!left.resolved || !right.resolved) return UNRESOLVED;
+    return { resolved: true, ids: [.../* @__PURE__ */ new Set([...left.ids, ...right.ids])] };
+  }
+  return UNRESOLVED;
+}
+function collectElementAttrs(opening, consts, dynamicAttrs, lineAt) {
+  const statics = [];
+  const patterns = [];
+  const attributes = opening.attributes ?? [];
+  for (const attr of attributes) {
+    if (attr.type !== "JSXAttribute") continue;
+    const kind = attrKind(attr);
+    if (!kind) continue;
+    const value = attr.value;
+    if (!value) continue;
+    let result = UNRESOLVED;
+    let valueSpan;
+    if (value.type === "Literal") {
+      const v = staticString(value);
+      result = v !== null && v.length > 0 ? { resolved: true, ids: [v] } : UNRESOLVED;
+      if (result.resolved) valueSpan = { start: value.start, end: value.end };
+    } else if (value.type === "JSXExpressionContainer") {
+      const expr = value.expression;
+      if (expr && expr.type !== "JSXEmptyExpression") {
+        result = evalIdExpression(expr, consts);
+        const inner = unwrapTsExpression(expr);
+        if (result.resolved && staticString(inner) !== null) {
+          valueSpan = { start: inner.start, end: inner.end };
         }
-        if (cj === "{") depth++;
-        else if (cj === "}") depth--;
-        i++;
       }
-      continue;
+      if (!result.resolved) {
+        dynamicAttrs.push({
+          kind,
+          attrName: kind === "element" ? "data-uidex" : `data-uidex-${kind}`,
+          line: lineAt(attr.start)
+        });
+        continue;
+      }
+    }
+    if (!result.resolved) continue;
+    for (const id of result.ids) {
+      const resolved = {
+        kind,
+        id,
+        start: attr.start,
+        isPattern: id.includes("*"),
+        // Only a single plain string literal is renameable in place.
+        ...result.ids.length === 1 && valueSpan ? { span: valueSpan } : {}
+      };
+      if (resolved.isPattern) patterns.push(resolved);
+      else statics.push(resolved);
     }
-    i++;
   }
-  return N;
+  return [...statics, ...patterns];
 }
-function findTagEnd(content, start) {
-  const N = content.length;
-  let i = start;
-  while (i < N) {
-    const c = content[i];
-    if (c === '"' || c === "'") {
-      i = skipString(content, i, c);
-      continue;
-    }
-    if (c === "`") {
-      i = skipTemplate(content, i);
-      continue;
-    }
-    if (c === "{") {
-      let depth = 1;
-      i++;
-      while (i < N && depth > 0) {
-        const cj = content[i];
-        if (cj === '"' || cj === "'") {
-          i = skipString(content, i, cj);
-          continue;
+function collectJSXFacts(parsed) {
+  const occurrences = [];
+  const dynamicAttrs = [];
+  const unannotatedInteractive = [];
+  const landmarks = [];
+  if (parsed.program === null) {
+    return { occurrences, dynamicAttrs, unannotatedInteractive, landmarks };
+  }
+  const consts = collectConstStrings(parsed.program);
+  const ancestors = [];
+  const visit = (node) => {
+    if (!isNode3(node)) return;
+    if (node.type === "JSXElement") {
+      const opening = node.openingElement;
+      const attrs = collectElementAttrs(
+        opening,
+        consts,
+        dynamicAttrs,
+        parsed.lineAt
+      );
+      const interactive = readInteractive(node, parsed.lineAt);
+      if (interactive) unannotatedInteractive.push(interactive);
+      if (attrs.length > 0) {
+        const snapshot = ancestors.slice();
+        for (const a of attrs) {
+          occurrences.push({
+            kind: a.kind,
+            id: a.id,
+            line: parsed.lineAt(a.start),
+            ancestors: snapshot,
+            ...a.span ? { span: a.span } : {}
+          });
         }
-        if (cj === "`") {
-          i = skipTemplate(content, i);
-          continue;
+      }
+      let pushed = attrs.length;
+      for (const a of attrs) ancestors.push({ kind: a.kind, id: a.id });
+      const landmark = readLandmark(opening, parsed.lineAt);
+      if (landmark) {
+        landmarks.push(landmark);
+        if (!attrs.some((a) => a.kind === "region")) {
+          ancestors.push({ kind: "region", id: landmark.tag });
+          pushed++;
         }
-        if (cj === "{") depth++;
-        else if (cj === "}") depth--;
-        i++;
       }
-      continue;
+      visitChildren(opening);
+      for (const child of node.children ?? []) {
+        visit(child);
+      }
+      const closing = node.closingElement;
+      if (isNode3(closing)) visitChildren(closing);
+      ancestors.length -= pushed;
+      return;
     }
-    if (c === ">") return i;
-    i++;
-  }
-  return -1;
+    visitChildren(node);
+  };
+  const visitChildren = (node) => {
+    for (const key of Object.keys(node)) {
+      if (key === "type" || key === "start" || key === "end") continue;
+      const value = node[key];
+      if (Array.isArray(value)) {
+        for (const item of value) visit(item);
+      } else {
+        visit(value);
+      }
+    }
+  };
+  visit(parsed.program);
+  return { occurrences, dynamicAttrs, unannotatedInteractive, landmarks };
 }
-
-// src/scanner/scan/extract.ts
-var JSDOC_BLOCK = /\/\*\*([\s\S]*?)\*\//g;
-function lineAt(content, index) {
-  let line = 1;
-  for (let i = 0; i < index && i < content.length; i++) {
-    if (content[i] === "\n") line++;
+function readLandmark(opening, lineAt) {
+  const name = opening.name;
+  if (!name || name.type !== "JSXIdentifier") return null;
+  const tag = String(name.name);
+  if (LANDMARK_TAGS.has(tag)) {
+    return { tag, line: lineAt(opening.start) };
   }
-  return line;
+  for (const attr of opening.attributes ?? []) {
+    if (attr.type !== "JSXAttribute") continue;
+    const attrName = attr.name;
+    if (!attrName || String(attrName.name) !== "role") continue;
+    const value = attr.value;
+    if (value && value.type === "Literal" && value.value === "region") {
+      return { tag: "region", line: lineAt(opening.start) };
+    }
+  }
+  return null;
 }
-function parseJSDoc(block) {
-  const lines = block.split("\n").map((l) => l.replace(/^\s*\*\s?/, "").replace(/^\s*\/?\*+/, ""));
-  let kind = null;
-  let id = null;
-  const acceptance = [];
-  const desc = [];
-  let notFlow = false;
-  for (const raw of lines) {
-    const line = raw.trim();
-    if (!line) continue;
-    const uidex = line.match(
-      /^@uidex\s+(page|feature|widget)\s+(\S+)(?:\s+-\s+(.+))?/
-    );
-    if (uidex) {
-      kind = uidex[1];
-      id = uidex[2];
-      if (uidex[3]) desc.push(uidex[3].trim());
+function readInteractive(element, lineAt) {
+  const opening = element.openingElement;
+  const name = opening.name;
+  if (!name || name.type !== "JSXIdentifier") return null;
+  const tag = String(name.name);
+  if (!INTERACTIVE_TAGS.has(tag)) return null;
+  let hasSpread = false;
+  for (const attr of opening.attributes ?? []) {
+    if (attr.type === "JSXSpreadAttribute") {
+      hasSpread = true;
       continue;
     }
-    if (/^@uidex:not-flow\b/.test(line)) {
-      notFlow = true;
-      continue;
+    if (attr.type === "JSXAttribute" && attrKind(attr) !== null) return null;
+  }
+  const nameHint = interactiveNameHint(element, opening);
+  return {
+    tag,
+    line: lineAt(opening.start),
+    hasSpread,
+    nameEnd: name.end,
+    ...nameHint ? { nameHint } : {}
+  };
+}
+function staticAttrValue(opening, attrName) {
+  for (const attr of opening.attributes ?? []) {
+    if (attr.type !== "JSXAttribute") continue;
+    const n = attr.name;
+    if (!n || String(n.name) !== attrName) continue;
+    const value = attr.value;
+    if (!value) return null;
+    if (value.type === "Literal") return staticString(value);
+    if (value.type === "JSXExpressionContainer") {
+      const expr = value.expression;
+      return expr ? staticString(unwrapTsExpression(expr)) : null;
     }
-    const accept = line.match(/^@acceptance\s+(.+)$/);
-    if (accept) {
-      acceptance.push(accept[1].trim());
-      continue;
+    return null;
+  }
+  return null;
+}
+function staticChildText(element) {
+  const parts = [];
+  for (const child of element.children ?? []) {
+    if (child.type === "JSXText") {
+      parts.push(String(child.value ?? ""));
     }
-    if (line.startsWith("@")) continue;
-    desc.push(line);
   }
+  return parts.join(" ").replace(/\s+/g, " ").trim();
+}
+function interactiveNameHint(element, opening) {
+  const ariaLabel = staticAttrValue(opening, "aria-label");
+  if (ariaLabel) return ariaLabel;
+  const text = staticChildText(element);
+  if (text) return text;
+  for (const attr of ["title", "name", "placeholder"]) {
+    const v = staticAttrValue(opening, attr);
+    if (v) return v;
+  }
+  return void 0;
+}
+function isNode3(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+
+// src/scanner/scan/extract.ts
+function parseFailureDiagnostic(file, parsed) {
+  const fatal = parsed.program === null || parsed.hasErrors && parsed.program.body.length === 0;
+  if (!fatal) return null;
   return {
-    kind,
-    id,
-    description: desc.join(" ").trim(),
-    acceptance,
-    notFlow
+    code: "parse-error",
+    severity: "warning",
+    message: "File could not be parsed \u2014 data-uidex attributes and flow facts in it were skipped, and their ids will drop out of the gen file",
+    file: file.displayPath,
+    line: 1,
+    hint: "Fix the file's syntax (or exclude it from .uidex.json sources) so the scanner can read its annotations"
   };
 }
 function extract(files) {
   return files.map((file) => {
-    const { exports, diagnostics } = extractUidexExports(file);
-    const out2 = {
-      file,
-      annotations: extractOne(file)
-    };
+    const parsed = parseSource(file);
+    const { exports, diagnostics } = extractUidexExports(file, parsed);
+    const parseFailure = parseFailureDiagnostic(file, parsed);
+    if (parseFailure) diagnostics.push(parseFailure);
+    const out2 = { file, annotations: [] };
+    out2.annotations = extractOne(file, parsed, out2);
     if (exports.length > 0) out2.metadata = exports;
     if (diagnostics.length > 0) out2.diagnostics = diagnostics;
+    const flows = collectFlowFacts(parsed, file.content);
+    if (flows.length > 0) out2.flows = flows;
+    const imports = collectImportFacts(parsed);
+    if (imports.length > 0) out2.imports = imports;
     return out2;
   });
 }
-function extractOne(file) {
+function extractOne(file, parsed, out2) {
   const annotations = [];
-  const { content, displayPath } = file;
-  for (const occ of collectJSXAncestry(content)) {
+  const { displayPath } = file;
+  const jsx = collectJSXFacts(parsed);
+  if (jsx.dynamicAttrs.length > 0) out2.dynamicAttrs = jsx.dynamicAttrs;
+  if (jsx.unannotatedInteractive.length > 0) {
+    out2.unannotatedInteractive = jsx.unannotatedInteractive;
+  }
+  if (jsx.landmarks.length > 0) out2.landmarks = jsx.landmarks;
+  for (const occ of jsx.occurrences) {
     annotations.push({
       kind: occ.kind,
       id: occ.id,
       file: displayPath,
       line: occ.line,
-      ...occ.ancestors.length > 0 ? { ancestors: occ.ancestors } : {}
+      ...occ.ancestors.length > 0 ? { ancestors: occ.ancestors } : {},
+      ...occ.span ? { span: occ.span } : {}
     });
   }
-  JSDOC_BLOCK.lastIndex = 0;
-  let jm;
-  while ((jm = JSDOC_BLOCK.exec(content)) !== null) {
-    const parsed = parseJSDoc(jm[1]);
-    const line = lineAt(content, jm.index);
-    if (parsed.notFlow) {
-      annotations.push({ kind: "not-flow", id: "", file: displayPath, line });
-    }
-    if (parsed.kind && parsed.id) {
-      const kind = parsed.kind === "page" ? "page-doc" : parsed.kind === "feature" ? "feature-doc" : "widget-doc";
-      annotations.push({
-        kind,
-        id: parsed.id,
-        file: displayPath,
-        line,
-        description: parsed.description || void 0,
-        acceptance: parsed.acceptance.length ? parsed.acceptance : void 0
-      });
-    } else if (parsed.acceptance.length > 0) {
-      annotations.push({
-        kind: "orphan-acceptance",
-        id: "",
-        file: displayPath,
-        line,
-        acceptance: parsed.acceptance
-      });
+  return annotations;
+}
+function collectImportFacts(parsed) {
+  if (parsed.program === null) return [];
+  const out2 = [];
+  for (const stmt of parsed.program.body) {
+    let source;
+    let isTypeOnly = false;
+    const names = [];
+    if (stmt.type === "ImportDeclaration") {
+      source = stmt.source;
+      isTypeOnly = stmt.importKind === "type";
+      for (const spec of stmt.specifiers ?? []) {
+        const local = spec.local;
+        if (local && local.type === "Identifier") {
+          names.push(String(local.name));
+        }
+      }
+    } else if ((stmt.type === "ExportNamedDeclaration" || stmt.type === "ExportAllDeclaration") && stmt.source) {
+      source = stmt.source;
+      isTypeOnly = stmt.exportKind === "type";
+    } else {
+      continue;
     }
+    if (!source || source.type !== "Literal") continue;
+    if (typeof source.value !== "string") continue;
+    out2.push({
+      specifier: source.value,
+      line: parsed.lineAt(stmt.start),
+      span: { start: stmt.start, end: stmt.end },
+      isTypeOnly,
+      names
+    });
   }
-  return annotations;
+  return out2;
 }
 
 // src/scanner/scan/resolve.ts
-import * as path3 from "path";
+import * as path4 from "path";
 
 // src/shared/entities/types.ts
 var ENTITY_KINDS = [
@@ -1567,6 +1520,7 @@ function freezeEntity(entity, flows) {
 function createRegistry() {
   const store = emptyStore();
   let flowsCache = null;
+  const patternCache = /* @__PURE__ */ new Map();
   const getFlows = () => {
     if (flowsCache === null) flowsCache = Array.from(store.flow.values());
     return flowsCache;
@@ -1576,6 +1530,7 @@ function createRegistry() {
     const key = entityKey(entity);
     store[entity.kind].set(key, entity);
     flowsCache = null;
+    patternCache.delete(entity.kind);
   };
   const get = (kind, id) => {
     assertEntityKind(kind);
@@ -1583,6 +1538,51 @@ function createRegistry() {
     if (raw === void 0) return void 0;
     return freezeEntity(raw, getFlows());
   };
+  const getPatternsForKind = (kind) => {
+    const cached = patternCache.get(kind);
+    if (cached !== void 0) return cached;
+    const patterns = [];
+    for (const [key, entity] of store[kind]) {
+      if (key.includes("*")) {
+        const segments = key.split("*");
+        patterns.push({
+          segments,
+          staticLength: segments.reduce((n, s) => n + s.length, 0),
+          entity
+        });
+      }
+    }
+    patternCache.set(
+      kind,
+      patterns
+    );
+    return patterns;
+  };
+  const matchesSegments = (segments, id) => {
+    const first = segments[0];
+    const last = segments[segments.length - 1];
+    if (!id.startsWith(first)) return false;
+    let pos = first.length;
+    for (let i = 1; i < segments.length - 1; i++) {
+      const idx = id.indexOf(segments[i], pos);
+      if (idx === -1) return false;
+      pos = idx + segments[i].length;
+    }
+    return id.endsWith(last) && id.length - last.length >= pos;
+  };
+  const matchPattern = (kind, id) => {
+    assertEntityKind(kind);
+    const patterns = getPatternsForKind(kind);
+    if (patterns.length === 0) return void 0;
+    let best;
+    for (const entry of patterns) {
+      if (matchesSegments(entry.segments, id) && (best === void 0 || entry.staticLength > best.staticLength)) {
+        best = entry;
+      }
+    }
+    if (best === void 0) return void 0;
+    return freezeEntity(best.entity, getFlows());
+  };
   const list = (kind) => {
     assertEntityKind(kind);
     const flows = getFlows();
@@ -1633,6 +1633,7 @@ function createRegistry() {
   return {
     add,
     get,
+    matchPattern,
     list,
     query,
     byScope,
@@ -1729,21 +1730,9 @@ function resolveConventions(c) {
 function kebab(str) {
   return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").replace(/[^a-zA-Z0-9-]/g, "").toLowerCase();
 }
-function baseName(file) {
-  const b = path3.posix.basename(file);
-  return b.replace(/\.(tsx|ts|jsx|js|mjs|cjs)$/, "");
-}
-var LANDMARK_RE = /<(header|nav|main|aside|footer)(\s[^>]*)?>|role=["']region["']/gi;
-function extractLandmarks(file) {
-  const out2 = [];
-  LANDMARK_RE.lastIndex = 0;
-  let m;
-  while ((m = LANDMARK_RE.exec(file.content)) !== null) {
-    const tag = m[1] ?? "region";
-    const line = 1 + file.content.slice(0, m.index).split("\n").length - 1;
-    out2.push({ tag, line });
-  }
-  return out2;
+function baseName(file) {
+  const b = path4.posix.basename(file);
+  return b.replace(/\.(tsx|ts|jsx|js|mjs|cjs)$/, "");
 }
 function fileMatchesAny(displayPath, patterns) {
   return patterns.some((g) => globToRegExp(g).test(displayPath));
@@ -1805,7 +1794,7 @@ function resolve2(ctx) {
   const routes = conventions.pages === "auto" ? detectRoutes(ctx.extracted.map((e) => e.file)) : [];
   const handledPageFiles = /* @__PURE__ */ new Set();
   for (const route of routes) {
-    const routeDir = path3.posix.dirname(route.file);
+    const routeDir = path4.posix.dirname(route.file);
     const wellKnownPath = `${routeDir}/${WELL_KNOWN_FILES.page}`;
     const wellKnownExp = exportFor(wellKnownPath, "page");
     const routeExp = exportFor(route.file, "page");
@@ -1859,7 +1848,7 @@ function resolve2(ctx) {
       const dir = extractFeatureDir(ef.file.displayPath, featureGlob);
       if (!dir) continue;
       conventionalFeatureDirs.add(dir);
-      const isWellKnown = path3.posix.basename(ef.file.displayPath) === WELL_KNOWN_FILES.feature;
+      const isWellKnown = path4.posix.basename(ef.file.displayPath) === WELL_KNOWN_FILES.feature;
       if (isWellKnown) wellKnownFeatureFileByDir.set(dir, ef.file.displayPath);
       const exp = exportFor(ef.file.displayPath, "feature");
       if (exp) {
@@ -1896,7 +1885,7 @@ function resolve2(ctx) {
       } else if (allExports.length > 0) {
         exp = allExports[0].exp;
       }
-      const id = exp && typeof exp.id === "string" ? exp.id : path3.posix.basename(dir);
+      const id = exp && typeof exp.id === "string" ? exp.id : path4.posix.basename(dir);
       const meta = exp ? buildMetaFromExport(exp) : void 0;
       const feature = {
         kind: "feature",
@@ -1992,8 +1981,8 @@ function resolve2(ctx) {
   }
   if (conventions.regions === "landmarks") {
     for (const ef of ctx.extracted) {
-      for (const lm of extractLandmarks(ef.file)) {
-        const id = kebab(`${lm.tag}`);
+      for (const lm of ef.landmarks ?? []) {
+        const id = lm.tag;
         if (!registry.get("region", id)) {
           const meta = metaWithComposes("region", id);
           const region = {
@@ -2104,7 +2093,7 @@ function resolve2(ctx) {
       const flowExport = (ff.metadata ?? []).find(
         (m) => m.kind === "flow" && typeof m.id === "string"
       );
-      const derived = extractFlowsFromSource(ff.file);
+      const derived = flowsFromFacts(ff);
       if (flowExport && typeof flowExport.id === "string" && derived.length === 1) {
         const base = derived[0];
         const flow = {
@@ -2159,60 +2148,21 @@ function computeScope(displayPath) {
   }
   return null;
 }
-function extractFlowsFromSource(file) {
-  const flows = [];
-  const source = file.content;
-  const describeRe = /test\.describe\(\s*(?:'([^']*)'|"([^"]*)")\s*,\s*\{[^}]*tag:\s*(?:'@uidex:flow'|"@uidex:flow"|\[[^\]]*@uidex:flow[^\]]*\])[^}]*\}/g;
-  let m;
-  while ((m = describeRe.exec(source)) !== null) {
-    const title = m[1] ?? m[2];
-    const id = kebab(title);
-    const line = 1 + source.slice(0, m.index).split("\n").length - 1;
-    const after = source.slice(m.index + m[0].length);
-    const arrow = after.match(/=>\s*\{/);
-    if (!arrow || arrow.index === void 0) continue;
-    const bodyStart = m.index + m[0].length + arrow.index + arrow[0].length;
-    let depth = 1;
-    let bodyEnd = -1;
-    for (let i = bodyStart; i < source.length; i++) {
-      if (source[i] === "{") depth++;
-      else if (source[i] === "}") {
-        depth--;
-        if (depth === 0) {
-          bodyEnd = i;
-          break;
-        }
-      }
-    }
-    if (bodyEnd === -1) continue;
-    const body = source.slice(bodyStart, bodyEnd);
-    const touches = captureUidexIds(body);
-    flows.push({
-      kind: "flow",
-      id,
-      loc: { file: file.displayPath, line },
-      touches: dedupe(touches.map((t) => t.id)),
-      steps: touches.filter((t) => t.action).map((t) => ({ entityId: t.id, action: t.action }))
-    });
-  }
-  return flows;
-}
-function captureUidexIds(body) {
-  const out2 = [];
-  const re = /uidex\(\s*(?:'([^']+)'|"([^"]+)"|`([^`$]+)`)\s*\)(?:\.(\w+)\s*\()?/g;
-  let m;
-  while ((m = re.exec(body)) !== null) {
-    out2.push({ id: m[1] || m[2] || m[3], action: m[4] });
-  }
-  return out2;
+function flowsFromFacts(ff) {
+  return (ff.flows ?? []).map((fact) => ({
+    kind: "flow",
+    id: kebab(fact.title),
+    loc: { file: ff.file.displayPath, line: fact.line },
+    touches: dedupe(fact.calls.map((c) => c.id)),
+    steps: fact.calls.filter((c) => c.action).map((c) => ({ entityId: c.id, action: c.action }))
+  }));
 }
 function dedupe(arr) {
   return Array.from(new Set(arr));
 }
 
 // src/scanner/scan/audit.ts
-import * as path4 from "path";
-var MARKER_FILENAMES = ["UIDEX_PAGE.md", "UIDEX_FEATURE.md"];
+import * as path5 from "path";
 function audit(opts) {
   const diagnostics = [];
   const { registry, extracted, files, config } = opts;
@@ -2222,22 +2172,15 @@ function audit(opts) {
   const scopeLeakEnabled = config.audit?.scopeLeak ?? true;
   const coverageEnabled = config.audit?.coverage ?? true;
   if (opts.resolveDiagnostics) diagnostics.push(...opts.resolveDiagnostics);
-  if (check) {
-    for (const f of files) {
-      const base = f.displayPath.split("/").pop() ?? "";
-      if (MARKER_FILENAMES.includes(base)) {
-        diagnostics.push({
-          code: "marker-md-ignored",
-          severity: "warning",
-          message: `Marker file "${base}" is ignored in v2; migrate to \`export const uidex\``,
-          file: f.displayPath
-        });
-      }
-    }
+  for (const ef of extracted) {
+    if (ef.diagnostics) diagnostics.push(...ef.diagnostics);
+  }
+  for (const ef of opts.flowExtracted ?? []) {
+    if (ef.diagnostics) diagnostics.push(...ef.diagnostics);
   }
   if (check && opts.generated !== void 0) {
     const outRel = opts.outputPath ?? config.output;
-    const fresh = normalizeLineEndings(opts.generated);
+    const fresh = normalizeForCheck(opts.generated);
     if (opts.existingOnDisk === null || opts.existingOnDisk === void 0) {
       diagnostics.push({
         code: "gen-missing",
@@ -2247,7 +2190,7 @@ function audit(opts) {
         hint: "Run `uidex scan` (without --check) to regenerate"
       });
     } else {
-      const existing = normalizeLineEndings(opts.existingOnDisk);
+      const existing = normalizeForCheck(opts.existingOnDisk);
       if (existing !== fresh) {
         const changed = diffEntities(existing, opts.generated, registry);
         const summary2 = formatChangedSummary(changed);
@@ -2261,22 +2204,6 @@ function audit(opts) {
       }
     }
   }
-  if (lint) {
-    for (const ef of extracted) {
-      for (const a of ef.annotations) {
-        const migration = legacyJsdocMigration(a);
-        if (!migration) continue;
-        diagnostics.push({
-          code: "legacy-jsdoc",
-          severity: "warning",
-          message: migration.message,
-          file: a.file,
-          line: a.line,
-          hint: migration.hint
-        });
-      }
-    }
-  }
   if (lint && acceptanceEnabled) {
     for (const kind of ["widget", "feature", "page"]) {
       for (const e of registry.list(kind)) {
@@ -2322,8 +2249,8 @@ function audit(opts) {
         if (typeof m.id !== "string") continue;
         const filePath = ef.file.displayPath;
         const wellKnownName = WELL_KNOWN_FILES[m.kind];
-        if (path4.posix.basename(filePath) === wellKnownName) continue;
-        const dir = path4.posix.dirname(filePath);
+        if (path5.posix.basename(filePath) === wellKnownName) continue;
+        const dir = path5.posix.dirname(filePath);
         const wellKnownPath = dir === "." ? wellKnownName : `${dir}/${wellKnownName}`;
         if (scannedPaths.has(wellKnownPath)) continue;
         const kindLabel = m.kind === "page" ? "Page" : "Feature";
@@ -2340,45 +2267,55 @@ function audit(opts) {
     }
   }
   if (lint) {
-    const dynamicAttrRe = /\bdata-uidex(?:-(region|widget|primitive))?\s*=\s*\{/g;
-    for (const f of files) {
-      let m;
-      dynamicAttrRe.lastIndex = 0;
-      while ((m = dynamicAttrRe.exec(f.content)) !== null) {
-        const kind = m[1] ?? "element";
-        let line = 1;
-        for (let i = 0; i < m.index; i++) if (f.content[i] === "\n") line++;
-        const attrName = m[1] ? `data-uidex-${m[1]}` : "data-uidex";
+    for (const ef of extracted) {
+      for (const fact of ef.dynamicAttrs ?? []) {
         diagnostics.push({
           code: "dynamic-attr",
           severity: "warning",
-          message: `\`${attrName}={\u2026}\` uses a dynamic expression; the scanner cannot resolve the ${kind} id statically`,
-          file: f.displayPath,
-          line,
-          hint: dynamicAttrHint(kind)
+          message: `\`${fact.attrName}={\u2026}\` uses a dynamic expression; the scanner cannot resolve the ${fact.kind} id statically`,
+          file: ef.file.displayPath,
+          line: fact.line,
+          hint: dynamicAttrHint(fact.kind)
         });
       }
     }
   }
   if (lint) {
-    for (const f of files) {
-      const tagRe = /<(button|a|input|select|textarea)(?=[\s/>])/g;
-      let m;
-      while ((m = tagRe.exec(f.content)) !== null) {
-        const afterTag = m.index + m[0].length;
-        const closeIdx = findJsxOpeningEnd(f.content, afterTag);
-        if (closeIdx === -1) continue;
-        const attrs = f.content.slice(afterTag, closeIdx);
-        if (attrs.includes("data-uidex")) continue;
-        let line = 1;
-        for (let i = 0; i < m.index; i++) if (f.content[i] === "\n") line++;
-        diagnostics.push({
-          code: "missing-element-annotation",
-          severity: "info",
-          message: `Interactive <${m[1].toLowerCase()}> without data-uidex annotation`,
-          file: f.displayPath,
-          line
-        });
+    const usedElementIds = new Set(registry.list("element").map((e) => e.id));
+    for (const ef of extracted) {
+      for (const fact of ef.unannotatedInteractive ?? []) {
+        if (fact.hasSpread) {
+          diagnostics.push({
+            code: "spread-attr",
+            severity: "info",
+            message: `Interactive <${fact.tag}> spreads dynamic props and has no static data-uidex attribute; if the annotation is forwarded via props the scanner cannot register it`,
+            file: ef.file.displayPath,
+            line: fact.line,
+            hint: "Prefer a string-literal data-uidex on the element itself, or annotate at the call site."
+          });
+        } else {
+          const id = uniqueElementId(fact, usedElementIds);
+          usedElementIds.add(id);
+          diagnostics.push({
+            code: "missing-element-annotation",
+            severity: "info",
+            message: `Interactive <${fact.tag}> without data-uidex annotation`,
+            file: ef.file.displayPath,
+            line: fact.line,
+            hint: `Add \`data-uidex="${id}"\` (or run \`uidex scan --fix\`).`,
+            fix: {
+              description: `Add data-uidex="${id}" to <${fact.tag}>`,
+              edits: [
+                {
+                  path: ef.file.sourcePath,
+                  start: fact.nameEnd,
+                  end: fact.nameEnd,
+                  replacement: ` data-uidex="${id}"`
+                }
+              ]
+            }
+          });
+        }
       }
     }
   }
@@ -2395,12 +2332,11 @@ function audit(opts) {
         }
       }
     }
-    for (const f of files) {
-      const importRe = /import\s+(?:[^'"]+)\s+from\s+['"]([^'"]+)['"]/g;
-      let m;
-      while ((m = importRe.exec(f.content)) !== null) {
-        const spec = m[1];
-        const baseName2 = spec.split("/").pop() ?? "";
+    for (const ef of extracted) {
+      const displayPath = ef.file.displayPath;
+      for (const imp of ef.imports ?? []) {
+        if (imp.isTypeOnly) continue;
+        const baseName2 = imp.specifier.split("/").pop() ?? "";
         const primitive = byName.get(
           baseName2.replace(/\.(tsx|ts|jsx|js|mjs|cjs)$/, "").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()
         );
@@ -2408,81 +2344,170 @@ function audit(opts) {
         const scope = primitive.scopes?.[0];
         if (!scope) continue;
         const [kind, id] = scope.split(":");
-        const importerSegments = f.displayPath.split("/");
+        const importerSegments = displayPath.split("/");
         if (importerSegments.includes(id) && importerSegments.includes(kind + "s")) {
           continue;
         }
         if (kind === "feature" && importerSegments.includes(id)) continue;
-        if (kind === "feature" && declaredFeatures.get(f.displayPath)?.has(id)) {
+        if (kind === "feature" && declaredFeatures.get(displayPath)?.has(id)) {
           continue;
         }
         diagnostics.push({
           code: "scope-leak",
           severity: "warning",
-          message: `Primitive "${primitive.id}" is scoped to ${scope} but is imported from ${f.displayPath}`,
-          file: f.displayPath
+          message: `Primitive "${primitive.id}" is scoped to ${scope} but is imported from ${displayPath}`,
+          file: displayPath,
+          line: imp.line
         });
       }
     }
   }
   if (lint && coverageEnabled) {
+    const factsByLoc = /* @__PURE__ */ new Map();
+    for (const ef of opts.flowExtracted ?? []) {
+      for (const fact of ef.flows ?? []) {
+        const lines = /* @__PURE__ */ new Map();
+        for (const call of fact.calls) {
+          if (!lines.has(call.id)) lines.set(call.id, call.line);
+        }
+        factsByLoc.set(`${ef.file.displayPath}:${fact.line}`, lines);
+      }
+    }
     for (const flow of registry.list("flow")) {
+      const callLines = factsByLoc.get(`${flow.loc.file}:${flow.loc.line}`);
       for (const touchedId of flow.touches) {
-        const found = registry.get("element", touchedId) ?? registry.get("widget", touchedId) ?? registry.get("region", touchedId);
+        const found = registry.get("element", touchedId) ?? registry.get("widget", touchedId) ?? registry.get("region", touchedId) ?? registry.matchPattern("element", touchedId) ?? registry.matchPattern("widget", touchedId) ?? registry.matchPattern("region", touchedId);
         if (!found) {
           diagnostics.push({
             code: "unknown-reference",
             severity: "warning",
             message: `Flow "${flow.id}" references unknown entity "${touchedId}"`,
             file: flow.loc.file,
-            line: flow.loc.line
+            // Point at the uidex() call itself when the spec facts are
+            // available; the describe line is the fallback.
+            line: callLines?.get(touchedId) ?? flow.loc.line
+          });
+        }
+      }
+    }
+  }
+  if (lint) {
+    const occurrences = /* @__PURE__ */ new Map();
+    for (const ef of extracted) {
+      for (const a of ef.annotations) {
+        if (a.kind !== "element" && a.kind !== "region" && a.kind !== "widget" && a.kind !== "primitive") {
+          continue;
+        }
+        const key = `${a.kind}:${a.id}`;
+        let list = occurrences.get(key);
+        if (!list) {
+          list = [];
+          occurrences.set(key, list);
+        }
+        list.push({ file: a.file, line: a.line });
+      }
+    }
+    for (const [key, list] of occurrences) {
+      const filesSeen = new Set(list.map((o) => o.file));
+      if (filesSeen.size < 2) continue;
+      const [kind, id] = key.split(/:(.*)/s);
+      const others = list.slice(1).map((o) => `${o.file}:${o.line}`).join(", ");
+      diagnostics.push({
+        code: "duplicate-id",
+        severity: kind === "widget" || kind === "primitive" ? "warning" : "info",
+        message: `${kind} id "${id}" is declared in ${filesSeen.size} files (also at ${others}); the registry keeps only one entry`,
+        file: list[0].file,
+        line: list[0].line,
+        entity: { kind, id },
+        hint: kind === "element" || kind === "region" ? "If these are variants of the same logical element this is fine; otherwise rename one (`uidex rename` updates flow references too)." : "Rename one of the definitions; two definitions with the same id silently merge."
+      });
+    }
+  }
+  if (lint && coverageEnabled) {
+    for (const ef of opts.flowExtracted ?? []) {
+      for (const fact of ef.flows ?? []) {
+        for (const dyn of fact.dynamicCalls ?? []) {
+          diagnostics.push({
+            code: "dynamic-flow-reference",
+            severity: "warning",
+            message: `\`uidex(\u2026)\` call in flow "${fact.title}" uses a dynamic expression; the id is invisible to coverage and registry validation`,
+            file: ef.file.displayPath,
+            line: dyn.line,
+            hint: "Use a string-literal id (component ids inside uidex() must be statically analysable)."
           });
         }
       }
     }
   }
+  if (lint && coverageEnabled) {
+    for (const ef of extracted) {
+      if (!ef.metadata) continue;
+      for (const m of ef.metadata) {
+        const check2 = (refKind, ids, spans) => {
+          for (let i = 0; i < (ids?.length ?? 0); i++) {
+            const refId = ids[i];
+            const found = registry.get(refKind, refId) ?? registry.matchPattern(refKind, refId);
+            if (found) continue;
+            diagnostics.push({
+              code: "unknown-reference",
+              severity: "warning",
+              message: `\`export const uidex\` in ${ef.file.displayPath} references unknown ${refKind} "${refId}"`,
+              file: ef.file.displayPath,
+              line: spans?.[i] ? lineOfOffset(ef.file.content, spans[i].start) : m.loc.line,
+              hint: `No ${refKind} with id "${refId}" exists in the registry; fix the reference or add the ${refKind}.`
+            });
+          }
+        };
+        check2("feature", m.features, m.featureSpans);
+        check2("widget", m.widgets, m.widgetSpans);
+      }
+    }
+  }
   const summary = {
     errors: diagnostics.filter((d) => d.severity === "error").length,
     warnings: diagnostics.filter((d) => d.severity === "warning").length
   };
   return { diagnostics, summary };
 }
-function legacyJsdocMigration(a) {
-  const quote = (s) => JSON.stringify(s);
-  const arr = (xs) => xs && xs.length > 0 ? `[${xs.map(quote).join(", ")}]` : "";
-  const entityHint = (kind) => {
-    const uidexKind = kind.charAt(0).toUpperCase() + kind.slice(1);
-    const parts = [`${kind}: ${quote(a.id)}`];
-    if (a.acceptance?.length) parts.push(`acceptance: ${arr(a.acceptance)}`);
-    return {
-      message: `Legacy JSDoc tag \`@uidex ${kind} ${a.id}\` is no longer recognised; migrate to \`export const uidex\``,
-      hint: `Replace with: export const uidex = { ${parts.join(", ")} } as const satisfies Uidex.${uidexKind}`
-    };
-  };
-  switch (a.kind) {
-    case "page-doc":
-      return entityHint("page");
-    case "feature-doc":
-      return entityHint("feature");
-    case "widget-doc":
-      return entityHint("widget");
-    case "not-flow":
-      return {
-        message: `Legacy JSDoc tag \`@uidex:not-flow\` is no longer recognised; migrate to \`export const uidex\``,
-        hint: `Replace with: export const uidex = { notFlow: true } as const satisfies Uidex.NotFlow`
-      };
-    case "orphan-acceptance":
-      return {
-        message: `Legacy JSDoc tag \`@acceptance\` is no longer recognised; migrate to the \`acceptance\` field on \`export const uidex\``,
-        hint: `Replace with: export const uidex = { /* kind */, acceptance: ${arr(a.acceptance)} } as const`
-      };
-    default:
-      return null;
+function lineOfOffset(content, offset) {
+  let line = 1;
+  for (let i = 0; i < offset && i < content.length; i++) {
+    if (content[i] === "\n") line++;
+  }
+  return line;
+}
+var TAG_FALLBACK_ID = {
+  a: "link",
+  button: "button",
+  input: "input",
+  select: "select",
+  textarea: "textarea"
+};
+function kebabId(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
+}
+function deriveElementId(fact) {
+  const fromHint = fact.nameHint ? kebabId(fact.nameHint) : "";
+  const capped = fromHint.split("-").filter(Boolean).slice(0, 5).join("-");
+  return capped || TAG_FALLBACK_ID[fact.tag] || fact.tag;
+}
+function uniqueElementId(fact, used) {
+  const base = deriveElementId(fact);
+  if (!used.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const candidate = `${base}-${n}`;
+    if (!used.has(candidate)) return candidate;
   }
 }
 function normalizeLineEndings(s) {
   return s.replace(/\r\n/g, "\n");
 }
+function normalizeForCheck(s) {
+  return normalizeLineEndings(s).replace(
+    /export const gitContext = \{[\s\S]*?\} as const/,
+    "export const gitContext = {} as const"
+  );
+}
 function formatChangedSummary(change) {
   const parts = [];
   const fmt = (kind, names) => {
@@ -2581,62 +2606,11 @@ function extractEntitiesArray(source) {
   }
   return null;
 }
-function findJsxOpeningEnd(src, start) {
-  let i = start;
-  while (i < src.length) {
-    const ch = src[i];
-    if (ch === ">" || ch === "/" && src[i + 1] === ">") return i;
-    if (ch === '"' || ch === "'" || ch === "`") {
-      i = skipString2(src, i);
-    } else if (ch === "{") {
-      i = skipBraces(src, i);
-    } else {
-      i++;
-    }
-  }
-  return -1;
-}
-function skipString2(src, start) {
-  const quote = src[start];
-  let i = start + 1;
-  while (i < src.length) {
-    if (src[i] === "\\" && quote !== "`") {
-      i += 2;
-      continue;
-    }
-    if (quote === "`" && src[i] === "$" && src[i + 1] === "{") {
-      i = skipBraces(src, i + 1);
-      continue;
-    }
-    if (src[i] === quote) return i + 1;
-    i++;
-  }
-  return i;
-}
-function skipBraces(src, start) {
-  let depth = 1;
-  let i = start + 1;
-  while (i < src.length && depth > 0) {
-    const ch = src[i];
-    if (ch === "{") {
-      depth++;
-      i++;
-    } else if (ch === "}") {
-      depth--;
-      i++;
-    } else if (ch === '"' || ch === "'" || ch === "`") {
-      i = skipString2(src, i);
-    } else {
-      i++;
-    }
-  }
-  return i;
-}
 function dynamicAttrHint(kind) {
   if (kind === "region") {
     return `Use a string literal: \`data-uidex-region="id"\`, or declare the region via \`export const uidex = { region: "id" } as const satisfies Uidex.Region\` on the file that passes the region value`;
   }
-  return `The scanner requires string-literal attribute values. If this component forwards the annotation via a prop, restructure so the caller provides the annotated element directly (e.g. via a slot or render prop) with a string-literal \`data-uidex\` attribute`;
+  return `The scanner resolves string literals, same-file const references, ternaries with literal branches, and template literals with static text (dynamic parts become \`*\` patterns). If this component forwards the annotation via a prop, restructure so the caller provides the annotated element directly (e.g. via a slot or render prop)`;
 }
 function stableStringify(value) {
   return JSON.stringify(value, stableReplacer);
@@ -2669,9 +2643,7 @@ function replacerSorted(_key, value) {
   }
   return value;
 }
-function emitIdUnion(name, ids, typeMode) {
-  if (typeMode === "loose") return `export type ${name} = string
-`;
+function emitIdUnion(name, ids) {
   if (ids.length === 0) return `export type ${name} = never
 `;
   const sorted = [...ids].sort();
@@ -2681,12 +2653,7 @@ ${body}
 `;
 }
 function emit(opts) {
-  const {
-    registry,
-    gitContext,
-    uidexImport = "uidex",
-    typeMode = "strict"
-  } = opts;
+  const { registry, gitContext, uidexImport = "uidex" } = opts;
   const routes = [...registry.list("route")].sort(
     (a, b) => a.path.localeCompare(b.path)
   );
@@ -2709,57 +2676,49 @@ function emit(opts) {
   lines.push(
     emitIdUnion(
       "PageId",
-      pages.map((e) => e.id),
-      typeMode
+      pages.map((e) => e.id)
     )
   );
   lines.push(
     emitIdUnion(
       "FeatureId",
-      features.map((e) => e.id),
-      typeMode
+      features.map((e) => e.id)
     )
   );
   lines.push(
     emitIdUnion(
       "WidgetId",
-      widgets.map((e) => e.id),
-      typeMode
+      widgets.map((e) => e.id)
     )
   );
   lines.push(
     emitIdUnion(
       "RegionId",
-      regions.map((e) => e.id),
-      typeMode
+      regions.map((e) => e.id)
     )
   );
   lines.push(
     emitIdUnion(
       "ElementId",
-      elements.map((e) => e.id),
-      typeMode
+      elements.map((e) => e.id)
     )
   );
   lines.push(
     emitIdUnion(
       "PrimitiveId",
-      primitives.map((e) => e.id),
-      typeMode
+      primitives.map((e) => e.id)
     )
   );
   lines.push(
     emitIdUnion(
       "FlowId",
-      flows.map((e) => e.id),
-      typeMode
+      flows.map((e) => e.id)
     )
   );
   lines.push(
     emitIdUnion(
       "RouteId",
-      routes.map((e) => e.path),
-      typeMode
+      routes.map((e) => e.path)
     )
   );
   lines.push("");
@@ -2872,22 +2831,33 @@ function parseGitHubRef(ref) {
 
 // src/scanner/scan/scaffold.ts
 import * as fs3 from "fs";
-import * as path5 from "path";
+import * as path6 from "path";
 function scaffoldWidgetSpec(opts) {
+  return scaffoldSpec({
+    registry: opts.registry,
+    kind: "widget",
+    id: opts.widgetId,
+    outDir: opts.outDir,
+    force: opts.force,
+    fixtureImport: opts.fixtureImport
+  });
+}
+function scaffoldSpec(opts) {
   const {
     registry,
-    widgetId,
+    kind,
+    id,
     outDir,
     force = false,
     fixtureImport = "./fixtures"
   } = opts;
-  const widget = registry.get("widget", widgetId);
-  if (!widget) {
-    throw new Error(`Widget "${widgetId}" not found in registry`);
+  const entity = registry.get(kind, id);
+  if (!entity) {
+    throw new Error(`${capitalize(kind)} "${id}" not found in registry`);
   }
-  const criteria = widget.meta?.acceptance ?? [];
-  const filename = `widget-${widgetId}.spec.ts`;
-  const outputPath = path5.resolve(outDir, filename);
+  const criteria = entity.meta?.acceptance ?? [];
+  const filename = kind === "widget" ? `widget-${id}.spec.ts` : `flow-${id}.spec.ts`;
+  const outputPath = path6.resolve(outDir, filename);
   if (fs3.existsSync(outputPath) && !force) {
     return {
       outputPath,
@@ -2896,15 +2866,14 @@ function scaffoldWidgetSpec(opts) {
       reason: `spec already exists at ${outputPath}; pass --force to overwrite`
     };
   }
-  const content = renderSpec({
-    widgetId,
-    criteria,
-    fixtureImport
-  });
-  fs3.mkdirSync(path5.dirname(outputPath), { recursive: true });
+  const content = renderSpec({ id, criteria, fixtureImport });
+  fs3.mkdirSync(path6.dirname(outputPath), { recursive: true });
   fs3.writeFileSync(outputPath, content, "utf8");
   return { outputPath, written: true, skipped: false };
 }
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
 function renderSpec(args) {
   const lines = [];
   lines.push(
@@ -2912,7 +2881,7 @@ function renderSpec(args) {
   );
   lines.push("");
   lines.push(
-    `test.describe(${JSON.stringify(args.widgetId)}, { tag: "@uidex:flow" }, () => {`
+    `test.describe(${JSON.stringify(args.id)}, { tag: "@uidex:flow" }, () => {`
   );
   if (args.criteria.length === 0) {
     lines.push(`  test("TODO: add acceptance criteria", async () => {`);
@@ -2935,7 +2904,7 @@ function renderSpec(args) {
 
 // src/scanner/scan/pipeline.ts
 import * as fs4 from "fs";
-import * as path6 from "path";
+import * as path7 from "path";
 function runScan(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const configs = opts.configs ?? discover({ cwd });
@@ -2964,10 +2933,9 @@ function runOne(dc, opts) {
   const gitContext = resolveGitContext({ cwd: configDir });
   const generated = emit({
     registry: resolved.registry,
-    gitContext,
-    typeMode: config.typeMode
+    gitContext
   });
-  const outputPath = path6.resolve(configDir, config.output);
+  const outputPath = path7.resolve(configDir, config.output);
   const outputRel = config.output;
   let existingOnDisk = null;
   if (opts.check) {
@@ -2977,12 +2945,16 @@ function runOne(dc, opts) {
       existingOnDisk = null;
     }
   }
+  const hasExtractDiagnostics = [...extracted, ...extractedFlows].some(
+    (ef) => (ef.diagnostics?.length ?? 0) > 0
+  );
   let auditResult;
-  if (opts.check || opts.lint || resolved.diagnostics.length > 0) {
+  if (opts.check || opts.lint || resolved.diagnostics.length > 0 || hasExtractDiagnostics) {
     auditResult = audit({
       registry: resolved.registry,
       extracted,
       files: sourceFiles,
+      flowExtracted: extractedFlows,
       config,
       check: opts.check,
       lint: opts.lint,
@@ -3003,34 +2975,281 @@ function runOne(dc, opts) {
   };
 }
 function writeScanResult(result) {
-  fs4.mkdirSync(path6.dirname(result.outputPath), { recursive: true });
+  fs4.mkdirSync(path7.dirname(result.outputPath), { recursive: true });
   fs4.writeFileSync(result.outputPath, result.generated, "utf8");
 }
 
+// src/scanner/scan/fix.ts
+import * as fs5 from "fs";
+import * as path8 from "path";
+function applyFixes(diagnostics) {
+  const entries = [];
+  for (const d of diagnostics) {
+    if (!d.fix) continue;
+    entries.push({
+      code: d.code,
+      description: d.fix.description,
+      file: d.file,
+      edits: d.fix.edits ?? [],
+      createFiles: d.fix.createFiles ?? [],
+      deleteFiles: d.fix.deleteFiles ?? []
+    });
+  }
+  if (entries.length === 0) return { applied: [], skipped: [] };
+  const seenEdits = /* @__PURE__ */ new Set();
+  const editsByFile = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    for (const edit of entry.edits) {
+      const key = `${edit.path}:${edit.start}:${edit.end}:${edit.replacement}`;
+      if (seenEdits.has(key)) continue;
+      seenEdits.add(key);
+      let list = editsByFile.get(edit.path);
+      if (!list) {
+        list = [];
+        editsByFile.set(edit.path, list);
+      }
+      list.push({ ...edit, entry });
+    }
+  }
+  for (const [filePath, edits] of editsByFile) {
+    let content;
+    try {
+      content = fs5.readFileSync(filePath, "utf8");
+    } catch {
+      for (const e of edits) e.entry.skippedReason ??= "file is unreadable";
+      continue;
+    }
+    edits.sort((a, b) => a.start - b.start || a.end - b.end);
+    const kept = [];
+    let prevEnd = -1;
+    for (const edit of edits) {
+      if (edit.start < prevEnd) {
+        edit.entry.skippedReason ??= "overlapping edit";
+        continue;
+      }
+      kept.push(edit);
+      prevEnd = edit.end;
+    }
+    for (let i = kept.length - 1; i >= 0; i--) {
+      const edit = kept[i];
+      content = content.slice(0, edit.start) + edit.replacement + content.slice(edit.end);
+    }
+    if (kept.length > 0) fs5.writeFileSync(filePath, content, "utf8");
+  }
+  for (const entry of entries) {
+    if (entry.skippedReason) continue;
+    for (const create of entry.createFiles) {
+      if (fs5.existsSync(create.path)) {
+        entry.skippedReason = `${path8.basename(create.path)} already exists`;
+        continue;
+      }
+      fs5.mkdirSync(path8.dirname(create.path), { recursive: true });
+      fs5.writeFileSync(create.path, create.content, "utf8");
+    }
+    if (entry.skippedReason) continue;
+    for (const del of entry.deleteFiles) {
+      try {
+        fs5.unlinkSync(del);
+      } catch {
+      }
+    }
+  }
+  const applied = [];
+  const skipped = [];
+  for (const entry of entries) {
+    const summary = {
+      code: entry.code,
+      description: entry.description,
+      file: entry.file
+    };
+    if (entry.skippedReason) {
+      skipped.push({ ...summary, reason: entry.skippedReason });
+    } else {
+      applied.push(summary);
+    }
+  }
+  return { applied, skipped };
+}
+
+// src/scanner/scan/rename.ts
+var ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function renameEntity(opts) {
+  const { cwd, kind, oldId, newId, force = false } = opts;
+  const manual = [];
+  const errors = [];
+  if (!ID_RE.test(newId)) {
+    return {
+      edits: 0,
+      manual,
+      errors: [`New id "${newId}" is not kebab-case`]
+    };
+  }
+  const configs = discover({ cwd });
+  if (configs.length === 0) {
+    return { edits: 0, manual, errors: [`No .uidex.json found under ${cwd}`] };
+  }
+  const edits = [];
+  for (const dc of configs) {
+    const { config, configDir } = dc;
+    const sourceFiles = walk(config.sources, {
+      cwd: configDir,
+      globalExcludes: config.exclude
+    });
+    const extracted = extract(sourceFiles);
+    const flowFiles = config.flows ? walk(
+      config.flows.map((glob) => ({ rootDir: ".", include: [glob] })),
+      { cwd: configDir, includeTests: true }
+    ) : [];
+    const extractedFlows = extract(flowFiles);
+    const scan = runScan({ cwd: configDir, configs: [dc] })[0];
+    const registry = scan.registry;
+    if (!registry.get(kind, oldId)) {
+      if (registry.matchPattern(kind, oldId)) {
+        errors.push(
+          `${kind} "${oldId}" only matches via a pattern id; pattern-backed ids cannot be renamed mechanically`
+        );
+      } else {
+        errors.push(`${kind} "${oldId}" not found in registry`);
+      }
+      continue;
+    }
+    if (registry.get(kind, newId) && !force) {
+      errors.push(
+        `${kind} "${newId}" already exists; pass --force to merge the ids`
+      );
+      continue;
+    }
+    const quoteAs = (content, start) => {
+      const q = content[start];
+      return q === '"' || q === "'" || q === "`" ? `${q}${newId}${q}` : `"${newId}"`;
+    };
+    for (const ef of extracted) {
+      for (const a of ef.annotations) {
+        if (a.kind !== kind || a.id !== oldId) continue;
+        if (a.span) {
+          edits.push({
+            path: ef.file.sourcePath,
+            start: a.span.start,
+            end: a.span.end,
+            replacement: quoteAs(ef.file.content, a.span.start)
+          });
+        } else {
+          manual.push({
+            file: a.file,
+            line: a.line,
+            reason: "attribute value is not a plain string literal (const reference, ternary, or template)"
+          });
+        }
+      }
+      for (const m of ef.metadata ?? []) {
+        if (kind === "widget" && m.kind === "widget" && m.id === oldId) {
+          if (m.idSpan) {
+            edits.push({
+              path: ef.file.sourcePath,
+              start: m.idSpan.start,
+              end: m.idSpan.end,
+              replacement: quoteAs(ef.file.content, m.idSpan.start)
+            });
+          } else {
+            manual.push({
+              file: ef.file.displayPath,
+              line: m.loc.line ?? 1,
+              reason: "widget export id is not a plain string literal"
+            });
+          }
+        }
+        if (kind === "widget" && m.widgets) {
+          for (let i = 0; i < m.widgets.length; i++) {
+            if (m.widgets[i] !== oldId) continue;
+            const span = m.widgetSpans?.[i];
+            if (span) {
+              edits.push({
+                path: ef.file.sourcePath,
+                start: span.start,
+                end: span.end,
+                replacement: quoteAs(ef.file.content, span.start)
+              });
+            }
+          }
+        }
+      }
+    }
+    for (const ef of extractedFlows) {
+      for (const fact of ef.flows ?? []) {
+        for (const call of fact.calls) {
+          if (call.id !== oldId) continue;
+          if (call.span) {
+            edits.push({
+              path: ef.file.sourcePath,
+              start: call.span.start,
+              end: call.span.end,
+              replacement: quoteAs(ef.file.content, call.span.start)
+            });
+          } else {
+            manual.push({
+              file: ef.file.displayPath,
+              line: call.line,
+              reason: "uidex() argument is not a plain string literal"
+            });
+          }
+        }
+      }
+    }
+  }
+  if (errors.length > 0) {
+    return { edits: 0, manual, errors };
+  }
+  if (edits.length === 0 && manual.length === 0) {
+    return {
+      edits: 0,
+      manual,
+      errors: [
+        `${kind} "${oldId}" has no editable occurrences (convention-derived ids like landmarks cannot be renamed)`
+      ]
+    };
+  }
+  const result = applyFixes([
+    {
+      code: "rename",
+      severity: "info",
+      message: "",
+      fix: {
+        description: `Rename ${kind} "${oldId}" to "${newId}"`,
+        edits
+      }
+    }
+  ]);
+  if (result.skipped.length > 0) {
+    errors.push(`Some edits were skipped: ${result.skipped[0].reason}`);
+  }
+  for (const r of runScan({ cwd })) writeScanResult(r);
+  return { edits: edits.length, manual, errors };
+}
+
 // src/scanner/scan/cli.ts
-import * as fs7 from "fs";
-import * as path9 from "path";
+import * as fs8 from "fs";
+import * as path11 from "path";
 
 // src/scanner/scan/ai/index.ts
 import * as p from "@clack/prompts";
 
 // src/scanner/scan/ai/providers/claude.ts
-import * as fs6 from "fs";
-import * as path8 from "path";
+import * as fs7 from "fs";
+import * as path10 from "path";
 
 // src/scanner/scan/ai/templates.ts
-import * as fs5 from "fs";
-import * as path7 from "path";
+import * as fs6 from "fs";
+import * as path9 from "path";
 function templatePath(rel) {
   const candidates = [
-    path7.resolve(__dirname, "../../templates", rel),
-    // dist/cli/cli.cjs    → ../../templates
-    path7.resolve(__dirname, "../../../templates", rel)
-    // src/scan/ai/foo.ts → ../../../templates
+    path9.resolve(__dirname, "../../templates", rel),
+    // dist/cli/cli.cjs         → ../../templates
+    path9.resolve(__dirname, "../../../../templates", rel)
+    // src/scanner/scan/ai → ../../../../templates
   ];
   for (const c of candidates) {
     try {
-      fs5.accessSync(c, fs5.constants.R_OK);
+      fs6.accessSync(c, fs6.constants.R_OK);
       return c;
     } catch {
       continue;
@@ -3042,24 +3261,39 @@ function templatePath(rel) {
   );
 }
 function readTemplate(rel) {
-  return fs5.readFileSync(templatePath(rel), "utf8");
+  return fs6.readFileSync(templatePath(rel), "utf8");
 }
 
 // src/scanner/scan/ai/providers/claude.ts
-var CLAUDE_FILES = [
-  { dest: ".claude/rules/uidex.md", template: "claude/rules.md" },
-  { dest: ".claude/commands/uidex/audit.md", template: "claude/audit.md" },
-  { dest: ".claude/commands/uidex/api.md", template: "claude/api.md" }
+var SKILL_FILES = [
+  { dest: ".claude/skills/uidex/SKILL.md", template: "claude/SKILL.md" },
+  {
+    dest: ".claude/skills/uidex/references/conventions.md",
+    template: "claude/references/conventions.md"
+  },
+  {
+    dest: ".claude/skills/uidex/references/audit.md",
+    template: "claude/references/audit.md"
+  },
+  {
+    dest: ".claude/skills/uidex/references/api.md",
+    template: "claude/references/api.md"
+  }
+];
+var LEGACY_FILES = [
+  ".claude/rules/uidex.md",
+  ".claude/commands/uidex/audit.md",
+  ".claude/commands/uidex/api.md"
 ];
 var claudeProvider = {
   id: "claude",
   label: "Claude Code",
-  description: "Adds .claude/rules/uidex.md, /uidex:audit, and /uidex:api slash commands.",
+  description: "Adds .claude/skills/uidex/ skill with conventions, audit, and API references.",
   async install({ cwd, force }) {
     const changes = [];
-    for (const file of CLAUDE_FILES) {
-      const dest = path8.join(cwd, file.dest);
-      const exists = fs6.existsSync(dest);
+    for (const file of SKILL_FILES) {
+      const dest = path10.join(cwd, file.dest);
+      const exists = fs7.existsSync(dest);
       if (exists && !force) {
         changes.push({
           path: file.dest,
@@ -3068,36 +3302,56 @@ var claudeProvider = {
         });
         continue;
       }
-      fs6.mkdirSync(path8.dirname(dest), { recursive: true });
-      fs6.writeFileSync(dest, readTemplate(file.template));
+      fs7.mkdirSync(path10.dirname(dest), { recursive: true });
+      fs7.writeFileSync(dest, readTemplate(file.template));
       changes.push({
         path: file.dest,
         action: exists ? "overwritten" : "created"
       });
     }
+    for (const rel of LEGACY_FILES) {
+      const dest = path10.join(cwd, rel);
+      if (fs7.existsSync(dest)) {
+        fs7.unlinkSync(dest);
+        changes.push({ path: rel, action: "removed" });
+      }
+    }
+    cleanupEmpty(path10.join(cwd, ".claude/commands/uidex"));
+    cleanupEmpty(path10.join(cwd, ".claude/commands"));
+    cleanupEmpty(path10.join(cwd, ".claude/rules"));
     return { changes };
   },
   async uninstall({ cwd }) {
     const changes = [];
-    for (const file of CLAUDE_FILES) {
-      const dest = path8.join(cwd, file.dest);
-      if (!fs6.existsSync(dest)) {
+    for (const file of SKILL_FILES) {
+      const dest = path10.join(cwd, file.dest);
+      if (!fs7.existsSync(dest)) {
         changes.push({ path: file.dest, action: "skipped", reason: "absent" });
         continue;
       }
-      fs6.unlinkSync(dest);
+      fs7.unlinkSync(dest);
       changes.push({ path: file.dest, action: "removed" });
     }
-    cleanupEmpty(path8.join(cwd, ".claude/commands/uidex"));
-    cleanupEmpty(path8.join(cwd, ".claude/commands"));
-    cleanupEmpty(path8.join(cwd, ".claude/rules"));
+    cleanupEmpty(path10.join(cwd, ".claude/skills/uidex/references"));
+    cleanupEmpty(path10.join(cwd, ".claude/skills/uidex"));
+    cleanupEmpty(path10.join(cwd, ".claude/skills"));
+    for (const rel of LEGACY_FILES) {
+      const dest = path10.join(cwd, rel);
+      if (fs7.existsSync(dest)) {
+        fs7.unlinkSync(dest);
+        changes.push({ path: rel, action: "removed" });
+      }
+    }
+    cleanupEmpty(path10.join(cwd, ".claude/commands/uidex"));
+    cleanupEmpty(path10.join(cwd, ".claude/commands"));
+    cleanupEmpty(path10.join(cwd, ".claude/rules"));
     return { changes };
   }
 };
 function cleanupEmpty(dir) {
   try {
-    const entries = fs6.readdirSync(dir);
-    if (entries.length === 0) fs6.rmdirSync(dir);
+    const entries = fs7.readdirSync(dir);
+    if (entries.length === 0) fs7.rmdirSync(dir);
   } catch {
   }
 }
@@ -3264,6 +3518,8 @@ async function run(opts) {
         return runScanCommand(cwd, flags, writer);
       case "scaffold":
         return runScaffold(cwd, positional.slice(1), flags, writer);
+      case "rename":
+        return runRename(cwd, positional.slice(1), flags, writer);
       case "ai": {
         const result = await runAiCommand({
           cwd,
@@ -3290,7 +3546,8 @@ function helpText2() {
     "Commands:",
     "  init                  Create a .uidex.json",
     "  scan [flags]          Run the scanner pipeline",
-    "  scaffold widget <id>  Emit a Playwright spec from a widget's acceptance",
+    "  scaffold <widget|page|feature> <id>  Emit a Playwright spec from declared acceptance",
+    "  rename <element|widget|region> <old-id> <new-id>  Rename an id everywhere (DOM attr, flows, exports)",
     "  ai <install|uninstall|providers>  Manage AI assistant integrations",
     "  api <METHOD> <PATH>              Call the uidex API",
     "  api --list                       Show available API routes",
@@ -3299,16 +3556,17 @@ function helpText2() {
     "",
     "Flags:",
     "  --check               Verify the on-disk gen file matches a fresh scan; exit non-zero on drift (read-only)",
-    "  --lint                Run lint diagnostics (missing annotations, scope leak, legacy JSDoc)",
+    "  --lint                Run lint diagnostics (missing annotations, scope leak, duplicate ids, coverage)",
     "  --audit               Equivalent to --check --lint (read-only)",
+    "  --fix                 Apply machine-generated fixes (add data-uidex to unannotated interactive elements, drop empty names), then rescan and write",
     "  --json                Emit JSON diagnostics on stdout",
     "  --force               (scaffold) overwrite existing spec",
     ""
   ].join("\n");
 }
 function runInit(cwd, w) {
-  const configPath = path9.join(cwd, CONFIG_FILENAME);
-  if (fs7.existsSync(configPath)) {
+  const configPath = path11.join(cwd, CONFIG_FILENAME);
+  if (fs8.existsSync(configPath)) {
     w.err(`.uidex.json already exists at ${configPath}`);
     return w.result(1);
   }
@@ -3317,16 +3575,16 @@ function runInit(cwd, w) {
     sources: [{ rootDir: "src" }],
     output: "src/uidex.gen.ts"
   };
-  fs7.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+  fs8.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   w.out(`Created ${configPath}`);
-  const gitignorePath = path9.join(cwd, ".gitignore");
+  const gitignorePath = path11.join(cwd, ".gitignore");
   const entry = "*.gen.ts";
-  if (fs7.existsSync(gitignorePath)) {
-    const existing = fs7.readFileSync(gitignorePath, "utf8");
+  if (fs8.existsSync(gitignorePath)) {
+    const existing = fs8.readFileSync(gitignorePath, "utf8");
     const hasEntry = existing.split("\n").some((line) => line.trim() === entry);
     if (!hasEntry) {
       const needsNewline = existing.length > 0 && !existing.endsWith("\n");
-      fs7.appendFileSync(
+      fs8.appendFileSync(
         gitignorePath,
         `${needsNewline ? "\n" : ""}${entry}
 `,
@@ -3335,21 +3593,33 @@ function runInit(cwd, w) {
       w.out(`Appended ${entry} to ${gitignorePath}`);
     }
   } else {
-    fs7.writeFileSync(gitignorePath, `${entry}
+    fs8.writeFileSync(gitignorePath, `${entry}
 `, "utf8");
     w.out(`Created ${gitignorePath} with ${entry}`);
   }
   return w.result(0);
 }
 function runScanCommand(cwd, flags, w) {
-  const check = Boolean(flags.check || flags.audit);
-  const lint = Boolean(flags.lint || flags.audit);
+  const fix = Boolean(flags.fix);
+  const check = !fix && Boolean(flags.check || flags.audit);
+  const lint = Boolean(flags.lint || flags.audit || fix);
   const asJson = Boolean(flags.json);
-  const configs = discover({ cwd });
+  let configs = discover({ cwd });
   if (configs.length === 0) {
     w.err(`No ${CONFIG_FILENAME} found under ${cwd}`);
     return w.result(1);
   }
+  let fixed = [];
+  let fixSkipped = [];
+  if (fix) {
+    const discovery = runScan({ cwd, check: true, lint: true, configs });
+    const result = applyFixes(
+      discovery.flatMap((r) => r.audit?.diagnostics ?? [])
+    );
+    fixed = result.applied;
+    fixSkipped = result.skipped;
+    configs = discover({ cwd });
+  }
   const results = runScan({ cwd, check, lint, configs });
   if (!check) {
     for (const r of results) writeScanResult(r);
@@ -3364,9 +3634,21 @@ function runScanCommand(cwd, flags, w) {
     { errors: 0, warnings: 0 }
   );
   if (asJson) {
-    const out2 = { diagnostics: allDiagnostics, summary };
+    const out2 = {
+      diagnostics: allDiagnostics.map(jsonDiagnostic),
+      summary,
+      ...fix ? { fixed, fixSkipped } : {}
+    };
     w.out(JSON.stringify(out2, null, 2));
   } else {
+    for (const f of fixed) {
+      w.out(`FIXED [${f.code}] ${f.file ?? ""} ${f.description}`);
+    }
+    for (const s of fixSkipped) {
+      w.out(
+        `SKIPPED [${s.code}] ${s.file ?? ""} ${s.description} (${s.reason})`
+      );
+    }
     for (const r of results) {
       if (check) {
         w.out(`Checked ${r.outputPath}`);
@@ -3376,7 +3658,10 @@ function runScanCommand(cwd, flags, w) {
       for (const d of r.audit?.diagnostics ?? []) {
         const loc = d.file ? `${d.file}${d.line ? `:${d.line}` : ""}` : "";
         const stream = d.severity === "error" ? w.err : w.out;
-        stream(`${d.severity.toUpperCase()} [${d.code}] ${loc} ${d.message}`);
+        const fixable = d.fix && !fix ? " [fixable: run with --fix]" : "";
+        stream(
+          `${d.severity.toUpperCase()} [${d.code}] ${loc} ${d.message}${fixable}`
+        );
         if (d.hint) stream(`  hint: ${d.hint}`);
       }
     }
@@ -3387,20 +3672,27 @@ function runScanCommand(cwd, flags, w) {
   const exit = summary.errors > 0 ? 1 : 0;
   return w.result(exit);
 }
+function jsonDiagnostic(d) {
+  const { fix, ...rest } = d;
+  return fix ? { ...rest, fixable: true } : rest;
+}
+var SCAFFOLD_KINDS = /* @__PURE__ */ new Set(["widget", "page", "feature"]);
 function runScaffold(cwd, args, flags, w) {
   const [kind, id] = args;
-  if (kind !== "widget" || !id) {
-    w.err("Usage: uidex scaffold widget <id> [--force]");
+  if (!kind || !SCAFFOLD_KINDS.has(kind) || !id) {
+    w.err("Usage: uidex scaffold <widget|page|feature> <id> [--force]");
     return w.result(1);
   }
+  const scaffoldKind = kind;
   const results = runScan({ cwd });
   for (const r of results) {
-    const widget = r.registry.get("widget", id);
-    if (!widget) continue;
-    const outDir = path9.resolve(r.configDir, "e2e");
-    const result = scaffoldWidgetSpec({
+    const entity = r.registry.get(scaffoldKind, id);
+    if (!entity) continue;
+    const outDir = path11.resolve(r.configDir, "e2e");
+    const result = scaffoldSpec({
       registry: r.registry,
-      widgetId: id,
+      kind: scaffoldKind,
+      id,
       outDir,
       force: Boolean(flags.force)
     });
@@ -3411,9 +3703,43 @@ function runScaffold(cwd, args, flags, w) {
     w.out(`Wrote ${result.outputPath}`);
     return w.result(0);
   }
-  w.err(`Widget "${id}" not found in registry`);
+  w.err(
+    `${scaffoldKind.charAt(0).toUpperCase() + scaffoldKind.slice(1)} "${id}" not found in registry`
+  );
   return w.result(1);
 }
+var RENAME_KINDS = /* @__PURE__ */ new Set(["element", "widget", "region"]);
+function runRename(cwd, args, flags, w) {
+  const [kind, oldId, newId] = args;
+  if (!kind || !RENAME_KINDS.has(kind) || !oldId || !newId) {
+    w.err(
+      "Usage: uidex rename <element|widget|region> <old-id> <new-id> [--force]"
+    );
+    return w.result(1);
+  }
+  const result = renameEntity({
+    cwd,
+    kind,
+    oldId,
+    newId,
+    force: Boolean(flags.force)
+  });
+  for (const e of result.errors) w.err(e);
+  for (const m of result.manual) {
+    w.err(`MANUAL ${m.file}:${m.line} \u2014 ${m.reason}`);
+  }
+  if (result.errors.length > 0) return w.result(1);
+  w.out(
+    `Renamed ${kind} "${oldId}" \u2192 "${newId}" (${result.edits} edit(s)); gen file regenerated`
+  );
+  if (result.manual.length > 0) {
+    w.err(
+      `${result.manual.length} occurrence(s) need manual follow-up (listed above)`
+    );
+    return w.result(1);
+  }
+  return w.result(0);
+}
 function createWriter() {
   let stdout = "";
   let stderr = "";
@@ -3433,7 +3759,7 @@ export {
   CONFIG_FILENAME,
   ConfigError,
   DEFAULT_CONVENTIONS,
-  DEFAULT_TYPE_MODE,
+  applyFixes,
   audit,
   detectRoutes,
   discover,
@@ -3443,10 +3769,12 @@ export {
   globToRegExp,
   parseConfig,
   pathToId,
+  renameEntity,
   resolve2 as resolve,
   resolveGitContext,
   run as runCli,
   runScan,
+  scaffoldSpec,
   scaffoldWidgetSpec,
   validateConfig,
   walk,