@jay-framework/compiler-jay-html 0.25.4 → 0.26.0

package/dist/index.d.cts

@@ -102,6 +102,34 @@ declare function filterTagsByPhase(tags: ContractTag[], targetPhase: RenderingPh
  */
 declare function createPhaseContract(contract: Contract, targetPhase: RenderingPhase): Contract;
 
+/**
+ * Owns type-analysis state for one scope (DL#225). The TS type analysis (`ts.createProgram` inside
+ * `analyzeExportedTypes`) costs ~hundreds of ms per component file, and `parseJayFile` re-analyzes every
+ * local `src=` import on every call — once per SSR request in the dev server. A context memoizes results
+ * so repeat requests (and a component imported by many pages at build time) don't re-analyze.
+ *
+ * A context is created per owner (dev-server session, build run, CLI command, or **test**) and threaded
+ * through the resolver — not a module global — so the state's lifetime is the owner's and tests are
+ * isolated. DL#225 Phase 3 will make the context own a persistent `ts.LanguageService` here.
+ */
+interface AnalysisContext {
+    analyzeExportedTypes(fullPath: string, options: ResolveTsConfigOptions): JayType[];
+    /**
+     * Invalidate after a `.ts` / `.d.ts` / `.jay-contract` change. The cache keys on the analyzed file's
+     * own mtime (busts a direct edit), but a change to a *type it imports* (e.g. a regenerated contract
+     * `.d.ts`) without touching the component is not seen by mtime — so the dev-server watcher calls this.
+     * Currently clears everything (cheap; next request re-analyzes only the pages it renders).
+     */
+    noteFileChanged(changedPath?: string): void;
+    /** Clear all cached analysis. */
+    clear(): void;
+}
+/**
+ * Create a fresh {@link AnalysisContext}. Each owner creates its own; callers thread it via the resolver.
+ * Backed by a persistent `ts.LanguageService` (DL#225) so repeat/incremental analysis is near-free and the
+ * cold `createProgram` cost is shared across a session.
+ */
+declare function createAnalysisContext(): AnalysisContext;
 interface JayImportResolver {
     resolveLink(importingModuleDir: string, link: string): string;
     /** Load a contract from an absolute file path */
@@ -135,7 +163,21 @@ interface JayImportResolver {
         filePath: string;
     } | null;
 }
+/**
+ * Create a resolver bound to an {@link AnalysisContext} (DL#225). Owners (dev-server session, build run,
+ * CLI command, test) create one — and typically one context — and thread it through `parseJayFile(…,
+ * resolver, …)`. Defaults to a fresh private context when none is passed.
+ */
+declare function createJayImportResolver(context?: AnalysisContext): JayImportResolver;
 declare const JAY_IMPORT_RESOLVER: JayImportResolver;
+/** Fully reset the default resolver's analysis state. */
+declare function clearExportedTypesCache(): void;
+/**
+ * Note a changed file on the default context (dev-server watcher). Bumps just that file's version so the
+ * LanguageService re-reads it and re-checks dependents — incremental, keeping the rest of the program warm
+ * (vs a full reset). A dev server is one process = one default context, so this stays naturally scoped.
+ */
+declare function noteExportedTypesFileChanged(changedPath: string): void;
 
 interface JayContractImportLink {
     module: string;
@@ -334,6 +376,46 @@ declare function assignCoordinatesToJayHtml(jayHtml: string, headlessContractNam
  */
 declare function assignCoordinates(body: HTMLElement, options: AssignCoordinatesOptions): AssignCoordinatesResult;
 
+/**
+ * Dev-mode source-editing markers (Design Log #219).
+ *
+ * A pure `string -> string` transform over the ORIGINAL on-disk jay-html, run in the
+ * dev-server pre-render pipeline BEFORE slow-render. It injects dev-only attributes that
+ * let the source-editing inspector map a rendered pixel back to its jay-html source:
+ *
+ * - `jay-dev-src="from:to"` — 1-based line range into the original file, on every element
+ *   under `<body>`. A plain static attribute; the compilers pass it through verbatim.
+ * - `jay-dev-item="{<trackBy>}"` — a BOUND attribute on every `forEach` item root, so the
+ *   compiler emits the live record id per item and keeps it current on list updates.
+ *
+ * Line offsets are taken against the original source here (not the slow-render re-serialized
+ * markup), so the line values stay faithful to the author's file.
+ *
+ * Note: a region-prop marker (`jay-dev-prop-*`) was planned but dropped — a region's prop
+ * bindings are parent-scoped while its only rendered elements are child-scoped, so there is no
+ * DOM element on which such a bound attribute could resolve. The inspector instead reads the
+ * region's source fragment (contract + binding expressions) via `jay-dev-src`. See DL#219
+ * Implementation Results.
+ */
+declare const DEV_SRC_ATTR = "jay-dev-src";
+declare const DEV_ITEM_ATTR = "jay-dev-item";
+/** Contract name of a headless region (`<jay:NAME …>`), stamped on the region tag. */
+declare const DEV_REGION_ATTR = "jay-dev-region";
+/** JSON of a region's STATIC (non-bound, non-directive) props — the live identity values the
+ *  inspector can surface without reading source. Bound props stay source-only (parent-scoped). */
+declare const DEV_REGION_PROPS_ATTR = "jay-dev-region-props";
+/** The region's own `<jay:…>` line range, attached to the region's rendered root alongside
+ *  `jay-dev-region`. Distinct from that element's own `jay-dev-src` (which is the element's lines):
+ *  the region root is a shared element (the scope-anchor wrapper, or a ref-less region's single
+ *  child), so the region's source lives in its own attribute to avoid a dedicated DOM level. */
+declare const DEV_REGION_SRC_ATTR = "jay-dev-region-src";
+/**
+ * Inject dev-mode source markers into a jay-html string and return the serialized result.
+ * Elements outside `<body>` (e.g. `<head>`, the jay-data script) are left untouched.
+ * Idempotent: elements that already carry a marker are not re-stamped.
+ */
+declare function injectDevMarkers(jayHtml: string): string;
+
 declare function parseJayFile(html: string, filename: string, filePath: string, options: ResolveTsConfigOptions, linkedContractResolver: JayImportResolver, projectRoot: string, 
 /** Optional source directory for resolving headfull FS files (jay-html, contracts).
  *  When parsing pre-rendered files, filePath is in build/pre-rendered/ but headfull
@@ -646,4 +728,4 @@ declare function resolveHeadlessInstances(preRenderedJayHtml: string, instanceDa
  */
 declare function hasSlowPhaseProperties(contract: Contract | undefined): boolean;
 
-export { type ActionDefinition, type AssignCoordinatesOptions, type AssignCoordinatesResult, type Contract, type ContractImportInfo, type ContractParam, type ContractParamKind, type ContractProp, type ContractResolver, type ContractTag, ContractTagType, type DiscoveredHeadlessInstance, ERROR_CONTRACT, ERROR_CONTRACT_MODULE, ERROR_CONTRACT_NAME, ERROR_CONTRACT_PLUGIN, type EnumToImport, type ForEachHeadlessInstance, type HeadlessContractInfo, type HeadlessInstanceDiscoveryResult, type HeadlessInstanceResolvedData, JAY_IMPORT_RESOLVER, type JayContractImportLink, type JayHeadlessImports, type JayHtmlScript, type JayHtmlSourceFile, type JayImportResolver, type PhaseViewStates, type RenderingPhase, type ServerElementOptions, type SlowRenderInput, type SlowRenderOutput, assignCoordinates, assignCoordinatesToJayHtml, buildInstanceCoordinateKey, compileAction, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, createPhaseContract, defaultContractResolver, discoverHeadlessInstances, filterTagsByPhase, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateElementHydrateFile, generateSandboxRootFile, generateServerElementFile, generateTypes, getEffectivePhase, getJayHtmlImports, getLinkedContractDir, hasSlowPhaseProperties, htmlElementTagNameMap, isBuiltInErrorContract, isTagInPhase, loadLinkedContract, parseAction, parseContract, parseEnumValues, parseIsEnum, parseJayFile, parseTemplateParts, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };
+export { type ActionDefinition, type AnalysisContext, type AssignCoordinatesOptions, type AssignCoordinatesResult, type Contract, type ContractImportInfo, type ContractParam, type ContractParamKind, type ContractProp, type ContractResolver, type ContractTag, ContractTagType, DEV_ITEM_ATTR, DEV_REGION_ATTR, DEV_REGION_PROPS_ATTR, DEV_REGION_SRC_ATTR, DEV_SRC_ATTR, type DiscoveredHeadlessInstance, ERROR_CONTRACT, ERROR_CONTRACT_MODULE, ERROR_CONTRACT_NAME, ERROR_CONTRACT_PLUGIN, type EnumToImport, type ForEachHeadlessInstance, type HeadlessContractInfo, type HeadlessInstanceDiscoveryResult, type HeadlessInstanceResolvedData, JAY_IMPORT_RESOLVER, type JayContractImportLink, type JayHeadlessImports, type JayHtmlScript, type JayHtmlSourceFile, type JayImportResolver, type PhaseViewStates, type RenderingPhase, type ServerElementOptions, type SlowRenderInput, type SlowRenderOutput, assignCoordinates, assignCoordinatesToJayHtml, buildInstanceCoordinateKey, clearExportedTypesCache, compileAction, compileContract, contractToAllPhaseViewStates, contractToImportsViewStateAndRefs, contractToPhaseViewState, createAnalysisContext, createJayImportResolver, createPhaseContract, defaultContractResolver, discoverHeadlessInstances, filterTagsByPhase, generateElementBridgeFile, generateElementDefinitionFile, generateElementFile, generateElementFileReactTarget, generateElementHydrateFile, generateSandboxRootFile, generateServerElementFile, generateTypes, getEffectivePhase, getJayHtmlImports, getLinkedContractDir, hasSlowPhaseProperties, htmlElementTagNameMap, injectDevMarkers, isBuiltInErrorContract, isTagInPhase, loadLinkedContract, noteExportedTypesFileChanged, parseAction, parseContract, parseEnumValues, parseIsEnum, parseJayFile, parseTemplateParts, renderRefsType, resolveHeadlessInstances, slowRenderTransform, validateContractPhases };

package/dist/index.js

@@ -1,9 +1,9 @@
-import { camelCase as camelCase$1, JayImportedType, JayString, JayUnknown, isObjectType as isObjectType$1, isImportedType, isRecursiveType, Imports, Import, RenderFragment, WithValidations, isArrayType as isArrayType$1, isAtomicType, isPromiseType, isEnumType, GenerateTarget, hasRefs, JayTypeAlias, JayUnionType, mkRefsTree, equalJayTypes, mkRef, JayComponentType, JayHTMLType, getModeFileExtension, isHtmlStringType, RuntimeMode, nestRefs, mergeRefsTrees, JayNumber, SourceFileFormat, JayEnumType, JayObjectType, JayArrayType, JayPromiseType, resolvePrimitiveType, JayRecursiveType, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION$1, ImportsFor, JAY_FULLSTACK_COMPONENTS, hoistFreeRefs, freeRefsAugmentedRefType, isComponentType as isComponentType$1, JayErrorType, JayOptionalType, JayRecordType, isOptionalType, isRecordType, resolvePluginManifest, resolvePluginComponent } from "@jay-framework/compiler-shared";
+import { camelCase as camelCase$1, Imports, Import, RenderFragment, JayUnknown, JayImportedType, JayString, isObjectType as isObjectType$1, isImportedType, isRecursiveType, WithValidations, isArrayType as isArrayType$1, isAtomicType, isPromiseType, isEnumType, GenerateTarget, hasRefs, JayTypeAlias, JayUnionType, mkRefsTree, equalJayTypes, mkRef, JayComponentType, JayHTMLType, getModeFileExtension, isHtmlStringType, RuntimeMode, nestRefs, mergeRefsTrees, JayNumber, SourceFileFormat, JayEnumType, JayObjectType, JayArrayType, JayPromiseType, resolvePrimitiveType, JayRecursiveType, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION$1, ImportsFor, JAY_FULLSTACK_COMPONENTS, hoistFreeRefs, freeRefsAugmentedRefType, isComponentType as isComponentType$1, JayErrorType, JayOptionalType, JayRecordType, isOptionalType, isRecordType, resolvePluginManifest, resolvePluginComponent } from "@jay-framework/compiler-shared";
 import path from "path";
 import { getLogger } from "@jay-framework/logger";
 import fs from "fs/promises";
 import fs$1 from "fs";
-import { analyzeExportedTypes } from "@jay-framework/compiler-analyze-exported-types";
+import { createTypeAnalyzer } from "@jay-framework/compiler-analyze-exported-types";
 import { createRequire } from "module";
 var commonjsGlobal = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof global !== "undefined" ? global : typeof self !== "undefined" ? self : {};
 function getDefaultExportFromCjs$1(x) {
@@ -5775,6 +5775,89 @@ parse$1.valid = valid_1.default;
 parse$1.Node = node_1.default;
 parse$1.TextNode = text_1.default;
 parse$1.NodeType = type_1.default;
+const DEV_SRC_ATTR = "jay-dev-src";
+const DEV_ITEM_ATTR = "jay-dev-item";
+const DEV_REGION_ATTR = "jay-dev-region";
+const DEV_REGION_PROPS_ATTR = "jay-dev-region-props";
+const DEV_REGION_SRC_ATTR = "jay-dev-region-src";
+const REGION_NON_PROP_ATTRS = /* @__PURE__ */ new Set([
+  "ref",
+  "if",
+  "foreach",
+  "trackby",
+  "key",
+  DEV_SRC_ATTR,
+  DEV_ITEM_ATTR,
+  DEV_REGION_ATTR,
+  DEV_REGION_PROPS_ATTR
+]);
+function injectDevMarkers(jayHtml) {
+  const root = parse_2(jayHtml, {
+    comment: true,
+    blockTextElements: { script: true, style: true }
+  });
+  const body = root.querySelector("body");
+  if (!body) return jayHtml;
+  const lineStarts = computeLineStarts(jayHtml);
+  for (const child of body.childNodes) {
+    if (child.nodeType === NodeType.ELEMENT_NODE) {
+      markElement(child, lineStarts);
+    }
+  }
+  return root.toString();
+}
+function markElement(element, lineStarts) {
+  const [start, end] = element.range;
+  if (!element.getAttribute(DEV_SRC_ATTR)) {
+    const fromLine = offsetToLine(start, lineStarts);
+    const toLine = offsetToLine(Math.max(start, end - 1), lineStarts);
+    element.setAttribute(DEV_SRC_ATTR, `${fromLine}:${toLine}`);
+  }
+  const forEach = element.getAttribute("forEach");
+  const trackBy = element.getAttribute("trackBy");
+  if (forEach && trackBy && !element.getAttribute(DEV_ITEM_ATTR)) {
+    element.setAttribute(DEV_ITEM_ATTR, `{${trackBy}}`);
+  }
+  const tagName = (element.rawTagName || "").toLowerCase();
+  if (tagName.startsWith("jay:") && !element.getAttribute(DEV_REGION_ATTR)) {
+    element.setAttribute(DEV_REGION_ATTR, tagName.slice(4));
+    const props = {};
+    for (const [key, value] of Object.entries(element.attributes)) {
+      if (REGION_NON_PROP_ATTRS.has(key.toLowerCase())) continue;
+      if (typeof value === "string" && !value.includes("{")) props[key] = value;
+    }
+    if (Object.keys(props).length > 0) {
+      element.setAttribute(DEV_REGION_PROPS_ATTR, encodeURIComponent(JSON.stringify(props)));
+    }
+  }
+  for (const child of element.childNodes) {
+    if (child.nodeType === NodeType.ELEMENT_NODE) {
+      markElement(child, lineStarts);
+    }
+  }
+}
+function computeLineStarts(src) {
+  const starts = [0];
+  for (let i = 0; i < src.length; i++) {
+    if (src.charCodeAt(i) === 10) starts.push(i + 1);
+  }
+  return starts;
+}
+function offsetToLine(offset, lineStarts) {
+  let lo = 0;
+  let hi = lineStarts.length - 1;
+  let line = 0;
+  while (lo <= hi) {
+    const mid = lo + hi >> 1;
+    if (lineStarts[mid] <= offset) {
+      line = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return line + 1;
+}
 const COORD_ATTR$1 = "jay-coordinate-base";
 const SCOPE_ATTR = "jay-scope";
 const AUTO_REF_PATTERN = /^AR\d+$/;
@@ -5877,6 +5960,20 @@ function assignHeadlessInstance(element, contractName, ref, parentCoord, options
     children.forEach((child) => wrapper.appendChild(child));
     element.appendChild(wrapper);
   }
+  const devSrc = element.getAttribute(DEV_SRC_ATTR);
+  const devRegion = element.getAttribute(DEV_REGION_ATTR);
+  const devRegionProps = element.getAttribute(DEV_REGION_PROPS_ATTR);
+  if (devRegion) {
+    const regionRoot = element.childNodes.find((n) => n.nodeType === NodeType.ELEMENT_NODE);
+    if (regionRoot) {
+      regionRoot.setAttribute(DEV_REGION_ATTR, devRegion);
+      if (devRegionProps) regionRoot.setAttribute(DEV_REGION_PROPS_ATTR, devRegionProps);
+      if (devSrc) regionRoot.setAttribute(DEV_REGION_SRC_ATTR, devSrc);
+    }
+  }
+  if (devSrc) element.removeAttribute(DEV_SRC_ATTR);
+  if (devRegion) element.removeAttribute(DEV_REGION_ATTR);
+  if (devRegionProps) element.removeAttribute(DEV_REGION_PROPS_ATTR);
   walkChildren(element, childScopeId, childScopeId, options, counter);
 }
 function walkForEachChildren(parent, itemScopeId, options, counter) {
@@ -13950,6 +14047,127 @@ function parseConditionForSlowRender(expr, slowContext, vars) {
     return { type: "runtime", code: fragment, simplifiedExpr: expr };
   }
 }
+const htmlElementTagNameMap = {
+  a: "HTMLAnchorElement",
+  abbr: "HTMLElement",
+  address: "HTMLElement",
+  applet: "HTMLAppletElement",
+  area: "HTMLAreaElement",
+  article: "HTMLElement",
+  aside: "HTMLElement",
+  audio: "HTMLAudioElement",
+  b: "HTMLElement",
+  base: "HTMLBaseElement",
+  basefont: "HTMLBaseFontElement",
+  bdi: "HTMLElement",
+  bdo: "HTMLElement",
+  blockquote: "HTMLQuoteElement",
+  body: "HTMLBodyElement",
+  br: "HTMLBRElement",
+  button: "HTMLButtonElement",
+  canvas: "HTMLCanvasElement",
+  caption: "HTMLTableCaptionElement",
+  cite: "HTMLElement",
+  code: "HTMLElement",
+  col: "HTMLTableColElement",
+  colgroup: "HTMLTableColElement",
+  data: "HTMLDataElement",
+  datalist: "HTMLDataListElement",
+  dd: "HTMLElement",
+  del: "HTMLModElement",
+  details: "HTMLDetailsElement",
+  dfn: "HTMLElement",
+  dialog: "HTMLDialogElement",
+  dir: "HTMLDirectoryElement",
+  div: "HTMLDivElement",
+  dl: "HTMLDListElement",
+  dt: "HTMLElement",
+  em: "HTMLElement",
+  embed: "HTMLEmbedElement",
+  fieldset: "HTMLFieldSetElement",
+  figcaption: "HTMLElement",
+  figure: "HTMLElement",
+  font: "HTMLFontElement",
+  footer: "HTMLElement",
+  form: "HTMLFormElement",
+  frame: "HTMLFrameElement",
+  frameset: "HTMLFrameSetElement",
+  h1: "HTMLHeadingElement",
+  h2: "HTMLHeadingElement",
+  h3: "HTMLHeadingElement",
+  h4: "HTMLHeadingElement",
+  h5: "HTMLHeadingElement",
+  h6: "HTMLHeadingElement",
+  head: "HTMLHeadElement",
+  header: "HTMLElement",
+  hgroup: "HTMLElement",
+  hr: "HTMLHRElement",
+  html: "HTMLHtmlElement",
+  i: "HTMLElement",
+  iframe: "HTMLIFrameElement",
+  img: "HTMLImageElement",
+  input: "HTMLInputElement",
+  ins: "HTMLModElement",
+  kbd: "HTMLElement",
+  label: "HTMLLabelElement",
+  legend: "HTMLLegendElement",
+  li: "HTMLLIElement",
+  link: "HTMLLinkElement",
+  main: "HTMLElement",
+  map: "HTMLMapElement",
+  mark: "HTMLElement",
+  marquee: "HTMLMarqueeElement",
+  menu: "HTMLMenuElement",
+  meta: "HTMLMetaElement",
+  meter: "HTMLMeterElement",
+  nav: "HTMLElement",
+  noscript: "HTMLElement",
+  object: "HTMLObjectElement",
+  ol: "HTMLOListElement",
+  optgroup: "HTMLOptGroupElement",
+  option: "HTMLOptionElement",
+  output: "HTMLOutputElement",
+  p: "HTMLParagraphElement",
+  param: "HTMLParamElement",
+  picture: "HTMLPictureElement",
+  pre: "HTMLPreElement",
+  progress: "HTMLProgressElement",
+  q: "HTMLQuoteElement",
+  rp: "HTMLElement",
+  rt: "HTMLElement",
+  ruby: "HTMLElement",
+  s: "HTMLElement",
+  samp: "HTMLElement",
+  script: "HTMLScriptElement",
+  section: "HTMLElement",
+  select: "HTMLSelectElement",
+  slot: "HTMLSlotElement",
+  small: "HTMLElement",
+  source: "HTMLSourceElement",
+  span: "HTMLSpanElement",
+  strong: "HTMLElement",
+  style: "HTMLStyleElement",
+  sub: "HTMLElement",
+  summary: "HTMLElement",
+  sup: "HTMLElement",
+  table: "HTMLTableElement",
+  tbody: "HTMLTableSectionElement",
+  td: "HTMLTableDataCellElement",
+  template: "HTMLTemplateElement",
+  textarea: "HTMLTextAreaElement",
+  tfoot: "HTMLTableSectionElement",
+  th: "HTMLTableHeaderCellElement",
+  thead: "HTMLTableSectionElement",
+  time: "HTMLTimeElement",
+  title: "HTMLTitleElement",
+  tr: "HTMLTableRowElement",
+  track: "HTMLTrackElement",
+  u: "HTMLElement",
+  ul: "HTMLUListElement",
+  var: "HTMLElement",
+  video: "HTMLVideoElement",
+  wbr: "HTMLElement"
+};
 function kebabToCamel(str2) {
   return str2.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
@@ -14044,7 +14262,7 @@ function getComponentName(tagName, importedSymbols, headlessContractNames) {
     }
     return { name: componentName, kind: "unknown" };
   }
-  if (importedSymbols.has(tagName)) {
+  if (importedSymbols.has(tagName) && !(tagName in htmlElementTagNameMap)) {
     return { name: tagName, kind: "headful" };
   }
   return null;
@@ -14157,127 +14375,6 @@ class Indent {
     return code.split("\n").map((_) => _.length > 0 ? indent + _ : _).join("\n");
   }
 }
-const htmlElementTagNameMap = {
-  a: "HTMLAnchorElement",
-  abbr: "HTMLElement",
-  address: "HTMLElement",
-  applet: "HTMLAppletElement",
-  area: "HTMLAreaElement",
-  article: "HTMLElement",
-  aside: "HTMLElement",
-  audio: "HTMLAudioElement",
-  b: "HTMLElement",
-  base: "HTMLBaseElement",
-  basefont: "HTMLBaseFontElement",
-  bdi: "HTMLElement",
-  bdo: "HTMLElement",
-  blockquote: "HTMLQuoteElement",
-  body: "HTMLBodyElement",
-  br: "HTMLBRElement",
-  button: "HTMLButtonElement",
-  canvas: "HTMLCanvasElement",
-  caption: "HTMLTableCaptionElement",
-  cite: "HTMLElement",
-  code: "HTMLElement",
-  col: "HTMLTableColElement",
-  colgroup: "HTMLTableColElement",
-  data: "HTMLDataElement",
-  datalist: "HTMLDataListElement",
-  dd: "HTMLElement",
-  del: "HTMLModElement",
-  details: "HTMLDetailsElement",
-  dfn: "HTMLElement",
-  dialog: "HTMLDialogElement",
-  dir: "HTMLDirectoryElement",
-  div: "HTMLDivElement",
-  dl: "HTMLDListElement",
-  dt: "HTMLElement",
-  em: "HTMLElement",
-  embed: "HTMLEmbedElement",
-  fieldset: "HTMLFieldSetElement",
-  figcaption: "HTMLElement",
-  figure: "HTMLElement",
-  font: "HTMLFontElement",
-  footer: "HTMLElement",
-  form: "HTMLFormElement",
-  frame: "HTMLFrameElement",
-  frameset: "HTMLFrameSetElement",
-  h1: "HTMLHeadingElement",
-  h2: "HTMLHeadingElement",
-  h3: "HTMLHeadingElement",
-  h4: "HTMLHeadingElement",
-  h5: "HTMLHeadingElement",
-  h6: "HTMLHeadingElement",
-  head: "HTMLHeadElement",
-  header: "HTMLElement",
-  hgroup: "HTMLElement",
-  hr: "HTMLHRElement",
-  html: "HTMLHtmlElement",
-  i: "HTMLElement",
-  iframe: "HTMLIFrameElement",
-  img: "HTMLImageElement",
-  input: "HTMLInputElement",
-  ins: "HTMLModElement",
-  kbd: "HTMLElement",
-  label: "HTMLLabelElement",
-  legend: "HTMLLegendElement",
-  li: "HTMLLIElement",
-  link: "HTMLLinkElement",
-  main: "HTMLElement",
-  map: "HTMLMapElement",
-  mark: "HTMLElement",
-  marquee: "HTMLMarqueeElement",
-  menu: "HTMLMenuElement",
-  meta: "HTMLMetaElement",
-  meter: "HTMLMeterElement",
-  nav: "HTMLElement",
-  noscript: "HTMLElement",
-  object: "HTMLObjectElement",
-  ol: "HTMLOListElement",
-  optgroup: "HTMLOptGroupElement",
-  option: "HTMLOptionElement",
-  output: "HTMLOutputElement",
-  p: "HTMLParagraphElement",
-  param: "HTMLParamElement",
-  picture: "HTMLPictureElement",
-  pre: "HTMLPreElement",
-  progress: "HTMLProgressElement",
-  q: "HTMLQuoteElement",
-  rp: "HTMLElement",
-  rt: "HTMLElement",
-  ruby: "HTMLElement",
-  s: "HTMLElement",
-  samp: "HTMLElement",
-  script: "HTMLScriptElement",
-  section: "HTMLElement",
-  select: "HTMLSelectElement",
-  slot: "HTMLSlotElement",
-  small: "HTMLElement",
-  source: "HTMLSourceElement",
-  span: "HTMLSpanElement",
-  strong: "HTMLElement",
-  style: "HTMLStyleElement",
-  sub: "HTMLElement",
-  summary: "HTMLElement",
-  sup: "HTMLElement",
-  table: "HTMLTableElement",
-  tbody: "HTMLTableSectionElement",
-  td: "HTMLTableDataCellElement",
-  template: "HTMLTemplateElement",
-  textarea: "HTMLTextAreaElement",
-  tfoot: "HTMLTableSectionElement",
-  th: "HTMLTableHeaderCellElement",
-  thead: "HTMLTableSectionElement",
-  time: "HTMLTimeElement",
-  title: "HTMLTitleElement",
-  tr: "HTMLTableRowElement",
-  track: "HTMLTrackElement",
-  u: "HTMLElement",
-  ul: "HTMLUListElement",
-  var: "HTMLElement",
-  video: "HTMLVideoElement",
-  wbr: "HTMLElement"
-};
 const isComponentType = (type2) => type2 instanceof JayComponentType || type2 instanceof JayTypeAlias || type2 instanceof JayUnionType && type2.ofTypes.every(isComponentType);
 const isComponentRef = (ref) => isComponentType(ref.elementType);
 const isCollectionRef = (ref) => ref.repeated;
@@ -14391,27 +14488,42 @@ function elementNameToJayType(element) {
 }
 class RefNameGenerator {
   nextId = 1;
-  constNamesToVariables = /* @__PURE__ */ new Map();
+  constNameOwners = /* @__PURE__ */ new Map();
   newAutoRefNameGenerator() {
     return "aR" + this.nextId++;
   }
-  newConstantName(refName, variables) {
+  /**
+   * Allocate a unique local const name for a ref.
+   *
+   * A const name is reused (returned unchanged) only when the SAME ref is requested again in the
+   * same render scope — "same ref" being identified by `identity`, not by `refName`. `refName` is
+   * only the base used to build the const (e.g. `input` → `refInput`); `identity` is the ref's
+   * stable key, which for an imported/headless ref is its full template path (e.g.
+   * `form.firstName.input`). This distinguishes "one ref used by several elements" (reuse) from
+   * "two distinct refs that happen to share a leaf tag name" (DL#226) — the latter get distinct
+   * consts (`refInput`, `refInput2`, …) instead of colliding.
+   *
+   * `identity` defaults to `refName`, which preserves prior behavior for page-own refs where
+   * `refName` is already the full, unique ref path.
+   */
+  newConstantName(refName, variables, identity = refName) {
     let suffix = 2;
     let constName = camelCase$1(`ref ${refName}`);
-    while (this.constNamesToVariables.has(constName)) {
-      if (this.constNamesToVariables.get(constName) === variables) {
+    while (this.constNameOwners.has(constName)) {
+      const owner = this.constNameOwners.get(constName);
+      if (owner.variables === variables && owner.identity === identity) {
         return constName;
       }
       constName = camelCase$1(`ref ${refName}${suffix++}`);
     }
-    this.constNamesToVariables.set(constName, variables);
+    this.constNameOwners.set(constName, { variables, identity });
     return constName;
   }
   /** Create a snapshot of the current state for use in parallel code generation paths. */
   clone() {
     const copy = new RefNameGenerator();
     copy.nextId = this.nextId;
-    copy.constNamesToVariables = new Map(this.constNamesToVariables);
+    copy.constNameOwners = new Map(this.constNameOwners);
     return copy;
   }
 }
@@ -15031,6 +15143,9 @@ const DIRECTIVE_ATTRIBUTES = /* @__PURE__ */ new Set([
   // DL#202 — template-side content-slot marker. A pure build-time authoring directive read by the
   // drift/sync differ; it rides into the flattened page copy (verbatim flatten) but must never render.
   "jay-content",
+  // DL#231 — editing-policy marker (`jay-policy="<name>"`) on a plain element or region tag. Read only
+  // by the editing-policy engine; never a component prop or a rendered attribute.
+  "jay-policy",
   AsyncDirectiveTypes.loading.directive,
   AsyncDirectiveTypes.resolved.directive,
   AsyncDirectiveTypes.rejected.directive
@@ -21641,7 +21756,11 @@ function renderElementRef$1(element, { dynamicRef, variables, importedRefNameToR
   if (element.attributes.ref) {
     if (importedRefNameToRef.has(element.attributes.ref)) {
       const importedRef = importedRefNameToRef.get(element.attributes.ref);
-      const uniqueConstName = refNameGenerator.newConstantName(importedRef.ref, variables);
+      const uniqueConstName = refNameGenerator.newConstantName(
+        importedRef.ref,
+        variables,
+        element.attributes.ref
+      );
       const refWithUniqueConstName = mkRef(
         importedRef.ref,
         element.attributes.ref,
@@ -21715,7 +21834,8 @@ function renderChildCompProps$1(element, { variables }, contractProps) {
   Object.keys(attributes2).forEach((attrName) => {
     let attrCanonical = attrName.toLowerCase();
     let attrKey = attrName.match(attributesRequiresQuotes$1) ? `"${attrName}"` : attrName;
-    if (attrCanonical === "if" || attrCanonical === "foreach" || attrCanonical === "trackby" || attrCanonical === "jay-coordinate-base" || attrCanonical === "jay-scope")
+    if (attrCanonical === "if" || attrCanonical === "foreach" || attrCanonical === "trackby" || attrCanonical === "jay-coordinate-base" || attrCanonical === "jay-scope" || // DL#231 — editing-policy marker on a region tag is a bare directive, never a component prop.
+    attrCanonical === "jay-policy")
       return;
     if (attrCanonical === "props") {
       isPropsDirectAssignment = true;
@@ -21750,7 +21870,11 @@ function renderChildCompProps$1(element, { variables }, contractProps) {
 function renderChildCompRef$1(element, { dynamicRef, variables, refNameGenerator, importedRefNameToRef }, componentName) {
   if (importedRefNameToRef.has(element.attributes.ref)) {
     const importedRef = importedRefNameToRef.get(element.attributes.ref);
-    const uniqueConstName = refNameGenerator.newConstantName(importedRef.ref, variables);
+    const uniqueConstName = refNameGenerator.newConstantName(
+      importedRef.ref,
+      variables,
+      element.attributes.ref
+    );
     const refWithUniqueConstName = mkRef(
       importedRef.ref,
       element.attributes.ref,
@@ -30927,10 +31051,22 @@ const YAML = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty
   visitAsync
 }, Symbol.toStringTag, { value: "Module" }));
 const require$1 = createRequire(import.meta.url);
-const JAY_IMPORT_RESOLVER = {
-  analyzeExportedTypes(fullPath, options) {
-    return analyzeExportedTypes(fullPath, options);
-  },
+function createAnalysisContext() {
+  const analyzer = createTypeAnalyzer();
+  return {
+    analyzeExportedTypes(fullPath, options) {
+      return analyzer.analyze(fullPath, options);
+    },
+    noteFileChanged(changedPath) {
+      if (changedPath) analyzer.noteFileChanged(changedPath);
+      else analyzer.clear();
+    },
+    clear() {
+      analyzer.clear();
+    }
+  };
+}
+const baseResolverMethods = {
   loadContract(fullPath) {
     const content = fs$1.readFileSync(fullPath).toString();
     return parseContract(content, fullPath);
@@ -31008,6 +31144,20 @@ const JAY_IMPORT_RESOLVER = {
     }
   }
 };
+function createJayImportResolver(context = createAnalysisContext()) {
+  return {
+    ...baseResolverMethods,
+    analyzeExportedTypes: (fullPath, options) => context.analyzeExportedTypes(fullPath, options)
+  };
+}
+const defaultAnalysisContext = createAnalysisContext();
+const JAY_IMPORT_RESOLVER = createJayImportResolver(defaultAnalysisContext);
+function clearExportedTypesCache() {
+  defaultAnalysisContext.clear();
+}
+function noteExportedTypesFileChanged(changedPath) {
+  defaultAnalysisContext.noteFileChanged(changedPath);
+}
 function buildPhaseMap(contract, headlessContracts, importResolver) {
   const phaseMap = /* @__PURE__ */ new Map();
   function processTag(tag, pathPrefix, parentPhase = "slow", contractDir) {
@@ -31482,6 +31632,11 @@ function hasSlowPhaseProperties(contract) {
 }
 export {
   ContractTagType,
+  DEV_ITEM_ATTR,
+  DEV_REGION_ATTR,
+  DEV_REGION_PROPS_ATTR,
+  DEV_REGION_SRC_ATTR,
+  DEV_SRC_ATTR,
   ERROR_CONTRACT,
   ERROR_CONTRACT_MODULE,
   ERROR_CONTRACT_NAME,
@@ -31490,11 +31645,14 @@ export {
   assignCoordinates,
   assignCoordinatesToJayHtml,
   buildInstanceCoordinateKey,
+  clearExportedTypesCache,
   compileAction,
   compileContract,
   contractToAllPhaseViewStates,
   contractToImportsViewStateAndRefs,
   contractToPhaseViewState,
+  createAnalysisContext,
+  createJayImportResolver,
   createPhaseContract,
   defaultContractResolver,
   discoverHeadlessInstances,
@@ -31512,9 +31670,11 @@ export {
   getLinkedContractDir,
   hasSlowPhaseProperties,
   htmlElementTagNameMap,
+  injectDevMarkers,
   isBuiltInErrorContract,
   isTagInPhase,
   loadLinkedContract,
+  noteExportedTypesFileChanged,
   parseAction,
   parseContract,
   parseEnumValues,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/compiler-jay-html",
-  "version": "0.25.4",
+  "version": "0.26.0",
   "description": "",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -34,12 +34,12 @@
   },
   "author": "",
   "dependencies": {
-    "@jay-framework/compiler-analyze-exported-types": "^0.25.4",
-    "@jay-framework/compiler-shared": "^0.25.4",
-    "@jay-framework/component": "^0.25.4",
-    "@jay-framework/logger": "^0.25.4",
-    "@jay-framework/runtime": "^0.25.4",
-    "@jay-framework/secure": "^0.25.4",
+    "@jay-framework/compiler-analyze-exported-types": "^0.26.0",
+    "@jay-framework/compiler-shared": "^0.26.0",
+    "@jay-framework/component": "^0.26.0",
+    "@jay-framework/logger": "^0.26.0",
+    "@jay-framework/runtime": "^0.26.0",
+    "@jay-framework/secure": "^0.26.0",
     "@types/js-yaml": "^4.0.9",
     "change-case": "^4.1.2",
     "he": "^1.2.0",
@@ -52,8 +52,8 @@
   },
   "devDependencies": {
     "@caiogondim/strip-margin": "^1.0.0",
-    "@jay-framework/4-react": "^0.25.4",
-    "@jay-framework/dev-environment": "^0.25.4",
+    "@jay-framework/4-react": "^0.26.0",
+    "@jay-framework/dev-environment": "^0.26.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/js-beautify": "^1",
     "@types/node": "^20.11.5",
@@ -65,7 +65,7 @@
     "react-dom": "^18.2.0",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",
-    "vite": "^5.0.11",
-    "vitest": "^1.2.1"
+    "vite": "^6.4.4",
+    "vitest": "^4.1.11"
   }
 }