@verajs/renderer 0.2.2 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/README.md +757 -225
  2. package/dist/development/vera-renderer-elements.d.ts +39 -0
  3. package/dist/development/vera-renderer-elements.d.ts.map +1 -0
  4. package/dist/development/vera-renderer-elements.js +193 -0
  5. package/dist/development/vera-renderer-elements.js.map +1 -0
  6. package/dist/development/vera-renderer-hydrate-slots.d.ts +94 -0
  7. package/dist/development/vera-renderer-hydrate-slots.d.ts.map +1 -0
  8. package/dist/development/vera-renderer-hydrate-slots.js +325 -0
  9. package/dist/development/vera-renderer-hydrate-slots.js.map +1 -0
  10. package/dist/development/vera-renderer-hydration.d.ts +332 -0
  11. package/dist/development/vera-renderer-hydration.d.ts.map +1 -0
  12. package/dist/development/vera-renderer-hydration.js +902 -0
  13. package/dist/development/vera-renderer-hydration.js.map +1 -0
  14. package/dist/development/vera-renderer-keyed.d.ts +25 -8
  15. package/dist/development/vera-renderer-keyed.d.ts.map +1 -1
  16. package/dist/development/vera-renderer-keyed.js +843 -268
  17. package/dist/development/vera-renderer-keyed.js.map +1 -1
  18. package/dist/development/vera-renderer-multi-window.d.ts +5 -0
  19. package/dist/development/vera-renderer-multi-window.d.ts.map +1 -0
  20. package/dist/development/vera-renderer-multi-window.js +40 -0
  21. package/dist/development/vera-renderer-multi-window.js.map +1 -0
  22. package/dist/development/vera-renderer-namespaces.d.ts +64 -0
  23. package/dist/development/vera-renderer-namespaces.d.ts.map +1 -0
  24. package/dist/development/vera-renderer-namespaces.js +94 -0
  25. package/dist/development/vera-renderer-namespaces.js.map +1 -0
  26. package/dist/development/vera-renderer-native-elements.d.ts +13 -0
  27. package/dist/development/vera-renderer-native-elements.d.ts.map +1 -0
  28. package/dist/development/vera-renderer-native-elements.js +231 -0
  29. package/dist/development/vera-renderer-native-elements.js.map +1 -0
  30. package/dist/development/vera-renderer-portal.d.ts +29 -0
  31. package/dist/development/vera-renderer-portal.d.ts.map +1 -0
  32. package/dist/development/vera-renderer-portal.js +167 -0
  33. package/dist/development/vera-renderer-portal.js.map +1 -0
  34. package/dist/development/vera-renderer-profiler.d.ts +48 -96
  35. package/dist/development/vera-renderer-profiler.d.ts.map +1 -1
  36. package/dist/development/vera-renderer-profiler.js +2632 -2142
  37. package/dist/development/vera-renderer-profiler.js.map +1 -1
  38. package/dist/development/vera-renderer-slots.d.ts +88 -92
  39. package/dist/development/vera-renderer-slots.d.ts.map +1 -1
  40. package/dist/development/vera-renderer-slots.js +1834 -1237
  41. package/dist/development/vera-renderer-slots.js.map +1 -1
  42. package/dist/development/vera-renderer-spread.d.ts +7 -41
  43. package/dist/development/vera-renderer-spread.d.ts.map +1 -1
  44. package/dist/development/vera-renderer-spread.js +539 -477
  45. package/dist/development/vera-renderer-spread.js.map +1 -1
  46. package/dist/development/vera-renderer-tag.d.ts +12 -3
  47. package/dist/development/vera-renderer-tag.d.ts.map +1 -1
  48. package/dist/development/vera-renderer-tag.js +671 -513
  49. package/dist/development/vera-renderer-tag.js.map +1 -1
  50. package/dist/development/vera-renderer-until.d.ts +24 -0
  51. package/dist/development/vera-renderer-until.d.ts.map +1 -0
  52. package/dist/development/vera-renderer-until.js +83 -0
  53. package/dist/development/vera-renderer-until.js.map +1 -0
  54. package/dist/development/vera-renderer.d.ts +48 -96
  55. package/dist/development/vera-renderer.d.ts.map +1 -1
  56. package/dist/development/vera-renderer.js +2607 -2104
  57. package/dist/development/vera-renderer.js.map +1 -1
  58. package/dist/vera-renderer-elements.min.js +2 -0
  59. package/dist/vera-renderer-elements.min.js.map +1 -0
  60. package/dist/vera-renderer-hydrate-slots.min.js +2 -0
  61. package/dist/vera-renderer-hydrate-slots.min.js.map +1 -0
  62. package/dist/vera-renderer-hydration.min.js +3 -0
  63. package/dist/vera-renderer-hydration.min.js.map +1 -0
  64. package/dist/vera-renderer-keyed.min.js +1 -1
  65. package/dist/vera-renderer-keyed.min.js.map +1 -1
  66. package/dist/vera-renderer-multi-window.min.js +2 -0
  67. package/dist/vera-renderer-multi-window.min.js.map +1 -0
  68. package/dist/vera-renderer-namespaces.min.js +2 -0
  69. package/dist/vera-renderer-namespaces.min.js.map +1 -0
  70. package/dist/vera-renderer-native-elements.min.js +2 -0
  71. package/dist/vera-renderer-native-elements.min.js.map +1 -0
  72. package/dist/vera-renderer-portal.min.js +2 -0
  73. package/dist/vera-renderer-portal.min.js.map +1 -0
  74. package/dist/vera-renderer-slots.min.js +1 -1
  75. package/dist/vera-renderer-slots.min.js.map +1 -1
  76. package/dist/vera-renderer-spread.min.js +1 -1
  77. package/dist/vera-renderer-spread.min.js.map +1 -1
  78. package/dist/vera-renderer-tag.min.js +1 -1
  79. package/dist/vera-renderer-tag.min.js.map +1 -1
  80. package/dist/vera-renderer-until.min.js +2 -0
  81. package/dist/vera-renderer-until.min.js.map +1 -0
  82. package/dist/vera-renderer.min.js +1 -1
  83. package/dist/vera-renderer.min.js.map +1 -1
  84. package/package.json +52 -9
  85. package/dist/development/vera-renderer-hydrate.d.ts +0 -147
  86. package/dist/development/vera-renderer-hydrate.d.ts.map +0 -1
  87. package/dist/development/vera-renderer-hydrate.js +0 -3136
  88. package/dist/development/vera-renderer-hydrate.js.map +0 -1
  89. package/dist/vera-renderer-hydrate.min.js +0 -2
  90. package/dist/vera-renderer-hydrate.min.js.map +0 -1
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vera-renderer-until.js","sources":["../../../shared-utils/src/diagnostic.ts","../../src/until-diagnostics.ts","../../src/until.ts"],"sourcesContent":["/**\n * **Where every diagnostic code is explained.** The URL is permanent: a released bundle is immutable, so every version\n * published points here for ever — the domain cannot lapse and `/e/` cannot be reorganized without breaking links in\n * code nobody can edit; the docs site redirects instead. `scripts/sync-diagnostics.mjs` imports this constant, so the\n * pages and the bundles can never disagree about where they are.\n */\nexport const DOCS = 'https://verajs.dev/e/';\n\n/**\n * **What this copy of the framework has already said** (Brian's ruling, 2026-11-12): the ONE memory behind `warnOnce`, `errorOnce`\n * and `hasWarned`, for DEVELOPMENT-ONLY warnings. It replaced the hand-written once-flags every package kept\n * (`saidLists`, `warnedDrop`, per-element WeakSets, per-key Sets: two naming styles, Brian: no names). **A warning that\n * ships to production keeps its memory at its site** (bytes, measured 2026-11-12: the shared memory costs +80–145 B gz\n * per bundle); development-only warnings use warnOnce. Module state by necessity, since \"once\" spans every call on the\n * page. One per BUNDLE COPY, exactly the scope each flag had, because this package is inlined into every bundle.\n * A code, or `code key` for a string key, in a Set. An object key (an element, a setup function) in a WeakMap, so its\n * entry goes with the object. Marked pure, so a bundle that never prints once drops both.\n */\nconst printed = /* @__PURE__ */ new Set<string>();\nconst printedOn = /* @__PURE__ */ new WeakMap<object, Map<string, Set<unknown>>>();\n/**\n * A once's KEY: none (once per page), a string (once per that string), an object (once per that object: an element, a\n * class, a setup function), or the PAIR `[object, value]`, a value key on that object (a store write: the object and its\n * property; a keyed list: the list and the duplicate key, compared as the list compares them, by value, so `1` and `'1'`\n * stay apart). A pair is the only array a key may be.\n */\ntype OnceKey = string | object | readonly [object, unknown];\n/** Where an object key's (code, value) lives: the value set for that code on that object, made on demand. */\nconst valuesOn = (on: object, code: string, make: boolean): Set<unknown> | undefined => {\n let codes = printedOn.get(on);\n if (codes === undefined) {\n if (!make) return undefined;\n printedOn.set(on, (codes = new Map()));\n }\n let values = codes.get(code);\n if (values === undefined && make) codes.set(code, (values = new Set()));\n return values;\n};\n/** The object and value of an object or pair key. */\nconst split = (key: object): readonly [object, unknown] => (Array.isArray(key) ? (key as unknown as readonly [object, unknown]) : [key, undefined]);\n/** Whether (code, key) is new, recording it if so. */\nconst firstTime = (code: string, key?: OnceKey): boolean => {\n if (key === undefined || typeof key === 'string') {\n const entry = key === undefined ? code : `${code} ${key}`;\n if (printed.has(entry)) return false;\n printed.add(entry);\n return true;\n }\n const [on, sub] = split(key);\n const values = valuesOn(on, code, true)!;\n if (values.has(sub)) return false;\n values.add(sub);\n return true;\n};\n\n/**\n * **One shape for every diagnostic the framework prints** — the short line production keeps, the whole sentence\n * development adds — so a package converting its messages writes a table and a call, never its own format.\n *\n * production `[vera] hydration: element: found <i> — https://verajs.dev/e/hydration-fallback`\n * development `[vera] hydration: element: found <i> — fell back to a client render: … (hydration-fallback)`\n *\n * `subject` is the free information — what the code already has at hand, naming the problem area — the same in both\n * builds. `prose` is development only: the package's table entry (`Prose`), called behind `__DEV__` at the call site so\n * the table goes unreferenced in production and rollup drops it whole. Production prints the code inside the link, so\n * the reader is one click from the explanation, which `scripts/sync-diagnostics.mjs` publishes from the same tables.\n *\n * **Every production message is coded** (Brian, 2026-11-11; this supersedes \"convert where smaller\", 2026-10-02):\n * consistency over a few bytes, so no package keeps a hand-written production line beside its table.\n */\n/*\n * The parameter names are deliberately unlike anything a caller holds: terser will not inline a function whose\n * parameter shadows a name at the call site (measured 2026-10-02 — directives passes its own `code`, and a parameter\n * called `code` left `((e,t,n)=>`…`)(0,t,n)` in its bundle, +8 B; renamed, the call folds to the bare template).\n */\n/**\n * **A misused API, named by its function** — the thrown-error twin of `diagnostic()`: `untrack: expected a function …\n * (untrack-not-function)`, function-first because a stack already names the source and the sweep reads that shape. The\n * prose comes from a package's table, behind `__DEV__`, so a development-only guard costs production nothing.\n */\nexport const misuse = (forName: string, withCode: string, andProse?: false | readonly [string, string?]) =>\n __DEV__ && andProse\n ? `${forName}: ${andProse[0]}${andProse[1] ? ` ${andProse[1]}` : ''} (${withCode})`\n : `${forName}: ${DOCS}${withCode}`;\n\n/**\n * **A misused API and what it was misused ABOUT** — `misuse()` with a subject, in `diagnostic()`'s ` — ` separator:\n * `parseFrontmatter: line 3 — https://verajs.dev/e/cms-frontmatter-unsupported`. The subject is the free information\n * (a line, a URL and its status) and prints in both builds. A sibling rather than an optional parameter on `misuse()`,\n * because `misuse()` is inlined into every bundle that throws and a conditional subject would tax all of them for a\n * shape few need; a sibling is tree-shaken where unused.\n */\nexport const misuseAbout = (forName: string, aboutSubject: string, withCode: string, andProse?: false | readonly [string, string?]) =>\n __DEV__ && andProse\n ? `${forName}: ${aboutSubject} — ${andProse[0]}${andProse[1] ? ` ${andProse[1]}` : ''} (${withCode})`\n : `${forName}: ${aboutSubject} — ${DOCS}${withCode}`;\n\nexport const diagnostic = (\n inArea: string,\n bySubject: string,\n withCode: string,\n andProse?: false | readonly [string, string?]\n) =>\n /** `__DEV__` HERE as well as at the call: production folds this to the one-line form, branch and all. */\n __DEV__ && andProse\n ? `[vera] ${inArea}: ${bySubject} — ${andProse[0]}${andProse[1] ? ` ${andProse[1]}` : ''} (${withCode})`\n : `[vera] ${inArea}: ${bySubject} — ${DOCS}${withCode}`;\n\n/**\n * **Text from outside — a file path, a YAML key, a URL, an error's message — quoted before it reaches a line.** A log is a\n * pipeline, and such text can be shaped by an author or a request: a newline in it forges a line, an ESC sequence hides\n * one (log injection). `JSON.stringify` escapes both; cut to 80 characters so one value cannot fill the log. @verajs/ssr\n * keeps a twin (it cannot import this), held equal by tests/ssr-coded-diagnostics.\n */\n/**\n * `max` caps the length (80 by default); `Infinity` keeps the whole text for a value worth reading in full — a site\n * owner's own path — which is still ESCAPED: truncation and escaping are separate jobs, and a path is not free of control\n * characters just because its owner wrote it (2026-10-09).\n */\nexport const quoted = (text: string, max = 80): string => JSON.stringify(text.length > max ? `${text.slice(0, max)}…` : text);\n\n/**\n * **The errors a package constructs, marked as its own** — so a wrapper that reports an inner refusal (cms's\n * `generateManifest` around a frontmatter line) carries it as it is: already formatted, its outside text already\n * quoted. Anything else is foreign, and quoted. Identity, never a shape test: a message can imitate ours, an identity\n * cannot. @verajs/ssr keeps a twin (it cannot import this).\n */\nconst ours = /* @__PURE__ */ new WeakSet<object>();\nexport const own = <E extends Error>(error: E): E => {\n ours.add(error);\n return error;\n};\nexport const isOwn = (error: unknown): boolean => typeof error === 'object' && error !== null && ours.has(error);\n\n/**\n * **Whether this copy has already said `code` (for `key`)**: for a GUARD only, where deciding to warn costs work worth\n * skipping once the warning is out (development's whole-tree walk for unwired directive attributes, an event-name\n * guess over every property of an element). A site that only prints calls `warnOnce`. Asks, never records.\n */\nexport const hasWarned = (code: string, key?: OnceKey): boolean => {\n if (key === undefined || typeof key === 'string') return printed.has(key === undefined ? code : `${code} ${key}`);\n const [on, sub] = split(key);\n return valuesOn(on, code, false)?.has(sub) === true;\n};\n\ntype Detail = false | readonly [string, string?] | (() => readonly [string, string?] | undefined);\n/**\n * The printer behind both, on one level. `andDetail` is `diagnostic()`'s prose, or a function returning it where building\n * the sentence costs something: it is called only the first time. `...andMore` rides beside the line behind '%s' (an\n * element, a thrown error), never inside it, so text from outside cannot forge a line. The console method is read at the\n * call, so a test that replaces `console.warn` sees it.\n */\nconst sayOnce =\n (level: 'warn' | 'error') =>\n (inArea: string, bySubject: string, withCode: string, andDetail?: Detail, forKey?: OnceKey, ...andMore: unknown[]): void => {\n if (!firstTime(withCode, forKey)) return;\n const line = diagnostic(inArea, bySubject, withCode, typeof andDetail === 'function' ? andDetail() : andDetail);\n if (andMore.length) console[level]('%s', line, ...andMore);\n else console[level](line);\n };\n/**\n * **A diagnostic said once per page** (per key, where one is given: a string, or an object such as the element it is\n * about): `diagnostic()`'s arguments, then the key, then what rides beside the line. Coded in production exactly as\n * `diagnostic()` is, because it IS `diagnostic()`. `errorOnce` is its twin on `console.error`, for a refusal a page should\n * not miss.\n */\nexport const warnOnce = /* @__PURE__ */ sayOnce('warn');\nexport const errorOnce = /* @__PURE__ */ sayOnce('error');\n","/** **`@verajs/renderer/until`'s diagnostics — DEVELOPMENT ONLY.** Its bundle's own table, merged into the renderer's json. */\nimport type { Prose } from '@verajs/shared-utils';\n\nexport const PROSE: Record<string, Prose> = {\n 'until-rejected': () => [\n 'the promise given to until() rejected, so its position kept showing the fallback; the browser reports the rejection itself.',\n 'To show an error, use `resource()` from `@verajs/store/resource`, whose `error` a template can render — or handle it in the promise (`.catch(…)`).',\n ],\n};\n","import { diagnostic } from '@verajs/shared-utils';\nimport { PROSE } from './until-diagnostics.js';\n\n/**\n * **`until(promise, fallback)` — a promise at a child position** (2026-10-26; the promise module the 2026-10-22 plan\n * named). `html\\`<p>${until(fetchUser(), html\\`<em>loading…</em>\\`)}</p>\\`` shows the fallback, then what the promise\n * resolves to. Built only on the renderer's `_$child$` protocol: core and the renderer carry nothing for it.\n *\n * - **The same promise again** (a re-render) keeps what is shown: no flash, no second subscription.\n * - **A new promise** shows the fallback again, and the old one's LATE answer is dropped — a slow first request can never\n * overwrite a newer one.\n * - **Removed before it settles** (`_$detach$`): the answer is dropped; nothing commits into a removed position.\n * - **A value that is not a promise** is shown at once.\n * - **A rejection** keeps the fallback, and the PLATFORM reports it: `until` handles only the value, so the rejection is\n * unhandled, and the browser prints it with its stack and fires `unhandledrejection`, which monitoring hears (Brian,\n * 2026-10-26: routing it through the `'error'` chain cost 157 B gz of 391; it is the app's own promise). Development\n * adds a hint. To SHOW an error, pass the caught promise — `until(load().catch(() => html\\`…\\`), fallback)` resolves to\n * the error view — or use `resource()`.\n * - **On a server** it renders the fallback (the server waits for no promise until the handoff lands); hydration draws\n * the same fallback again and the value replaces it.\n * - **No bare `${promise}`** (Brian: not now): written inline, a promise is a new one every render, a refetch loop.\n */\n/**\n * **On a server, a rejection is CONSUMED** (2026-10-26): the server serves the fallback and never shows the result (the\n * client makes its own request), and an unhandled rejection ends a Node process by default, so one failed fetch during a\n * server render would take the server down. `@verajs/ssr` sets this public flag at import, before anything renders.\n */\nconst onServer = (globalThis as { __veraSsrShimmed?: boolean }).__veraSsrShimmed === true;\ntype Until = { promise: unknown; fallback: unknown };\ntype State = { p: unknown; live: boolean };\ntype Part = { _$commit$(value: unknown): void };\n\n/** Hoisted: the applier's identity is its own continuity key (a new function per call would restart every render). */\nfunction applyUntil(this: Until, part: Part, previous: State | undefined): State {\n const promise = this.promise;\n if (previous !== undefined && previous.p === promise) return previous;\n if (previous !== undefined) previous.live = false;\n const state: State = { p: promise, live: true };\n if (typeof (promise as { then?: unknown } | null)?.then !== 'function') {\n part._$commit$(promise);\n return state;\n }\n part._$commit$(this.fallback);\n /** A rejection is RE-THROWN on a client — so the derived promise is unhandled and the platform reports it — and dropped on a server. */\n (promise as PromiseLike<unknown>).then(\n (value) => {\n if (state.live) part._$commit$(value);\n },\n (error) => {\n if (!onServer) throw error;\n }\n );\n /** Development: a hint beside the platform's own report (a SEPARATE handler: the chain above stays unhandled, so reported). */\n if (__DEV__)\n (promise as PromiseLike<unknown>).then(undefined, () => {\n if (state.live) console.warn(diagnostic('renderer', 'until()', 'until-rejected', __DEV__ && PROSE['until-rejected']()));\n });\n return state;\n}\n/** Told when its position goes away: an answer arriving later is dropped. */\napplyUntil._$detach$ = (previous: State | undefined) => {\n if (previous !== undefined) previous.live = false;\n};\n\nexport const until = (promise: unknown, fallback?: unknown): { _$child$: typeof applyUntil; promise: unknown; fallback: unknown } => ({ _$child$: applyUntil, promise, fallback });\n"],"names":[],"mappings":"AAAA;;;;;AAKG;AACI,MAAM,IAAI,GAAG,uBAAuB;AA2FpC,MAAM,UAAU,GAAG,CACxB,MAAc,EACd,SAAiB,EACjB,QAAgB,EAChB,QAA6C;AAE7C;AACA,OAAO,IAAI;AACT,MAAE,CAAA,OAAA,EAAU,MAAM,CAAA,EAAA,EAAK,SAAS,CAAA,GAAA,EAAM,QAAQ,CAAC,CAAC,CAAC,CAAA,EAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAA,CAAA,EAAI,QAAQ,CAAC,CAAC,CAAC,CAAA,CAAE,GAAG,EAAE,CAAA,EAAA,EAAK,QAAQ,CAAA,CAAA;MACnG,CAAA,OAAA,EAAU,MAAM,CAAA,EAAA,EAAK,SAAS,MAAM,IAAI,CAAA,EAAG,QAAQ,CAAA,CAAE;;ACvGpD,MAAM,KAAK,GAA0B;IAC1C,gBAAgB,EAAE,MAAM;QACtB,6HAA6H;QAC7H,oJAAoJ;AACrJ,KAAA;CACF;;ACLD;;;;;;;;;;;;;;;;;;AAkBG;AACH;;;;AAIG;AACH,MAAM,QAAQ,GAAI,UAA6C,CAAC,gBAAgB,KAAK,IAAI;AAKzF;AACA,SAAS,UAAU,CAAc,IAAU,EAAE,QAA2B,EAAA;AACtE,IAAA,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO;IAC5B,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,CAAC,KAAK,OAAO;AAAE,QAAA,OAAO,QAAQ;IACrE,IAAI,QAAQ,KAAK,SAAS;AAAE,QAAA,QAAQ,CAAC,IAAI,GAAG,KAAK;IACjD,MAAM,KAAK,GAAU,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;AAC/C,IAAA,IAAI,OAAQ,OAAqC,EAAE,IAAI,KAAK,UAAU,EAAE;AACtE,QAAA,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;AACvB,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC;;AAE5B,IAAA,OAAgC,CAAC,IAAI,CACpC,CAAC,KAAK,KAAI;QACR,IAAI,KAAK,CAAC,IAAI;AAAE,YAAA,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;AACvC,IAAA,CAAC,EACD,CAAC,KAAK,KAAI;AACR,QAAA,IAAI,CAAC,QAAQ;AAAE,YAAA,MAAM,KAAK;AAC5B,IAAA,CAAC,CACF;;AAED,IAAA,IAAI,OAAO;AACR,QAAA,OAAgC,CAAC,IAAI,CAAC,SAAS,EAAE,MAAK;YACrD,IAAI,KAAK,CAAC,IAAI;gBAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,OAAO,IAAI,KAAK,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;AACzH,QAAA,CAAC,CAAC;AACJ,IAAA,OAAO,KAAK;AACd;AACA;AACA,UAAU,CAAC,SAAS,GAAG,CAAC,QAA2B,KAAI;IACrD,IAAI,QAAQ,KAAK,SAAS;AAAE,QAAA,QAAQ,CAAC,IAAI,GAAG,KAAK;AACnD,CAAC;MAEY,KAAK,GAAG,CAAC,OAAgB,EAAE,QAAkB,MAA4E,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE;;;;"}
@@ -35,121 +35,73 @@ type TemplateResult = {
35
35
  };
36
36
 
37
37
  /**
38
- * @verajs/renderer — a ground-up, keyed, template-identity renderer.
38
+ * @verajs/renderer — a template-identity renderer.
39
39
  *
40
- * Replaces the Reef-derived renderer, which flattened every template to an HTML string and
41
- * re-parsed it on each change — O(whole template) work for a one-row edit, measured at 85 ms for a
42
- * two-row swap that lit-html does in 3.5 ms.
40
+ * A tagged template's `strings` array is interned per call site, so it keys a parsed `<template>`.
41
+ * An instance clones it and binds the expression positions; every later render of the same shape
42
+ * commits only the values that changed. Lists reconcile by index here, by key through
43
+ * `@verajs/renderer/keyed`.
43
44
  *
44
- * The architecture here is the one that wins that benchmark:
45
+ * Contracts the speed pays for:
46
+ * - The renderer owns its container below the mount point: a part that owns a whole parent clears it
47
+ * with one `textContent = ''`.
48
+ * - Do not `normalize()` rendered content — child anchors are text nodes.
49
+ * - A string renders as text, never as markup. There is no `innerHTML` sink.
45
50
  *
46
- * 1. A tagged template literal's `strings` array is frozen and IDENTICAL for every call from the
47
- * same call site, so it is a cache key for the template's static shape. The shape is parsed
48
- * ONCE into a `<template>` element with markers where the expressions go.
49
- * 2. Rendering clones that template and binds "parts" to the marker positions. Every later render
50
- * of the same shape only compares and commits the dynamic values — static content is never
51
- * touched again.
52
- * 3. Arrays reconcile KEYED (see `keyed()`), with head/tail fast paths and map-based moves, so a
53
- * reorder moves nodes instead of rebuilding them.
54
- *
55
- * Built in, where lit-html requires directive imports: keyed list reconciliation (`keyed`),
56
- * element refs (element-position expressions), toggled-DOM preservation (`hold`), and a
57
- * whole-range fast clear — one `textContent = ''` where lit removes thousands of nodes one at a
58
- * time. Like-for-like (lit-html + repeat + ref + cache: 5 021 B gzip), this file is ~28% smaller.
59
- *
60
- * What it deliberately does NOT have, which is why it is smaller than lit-html: no directive
61
- * protocol, no `noChange`/`nothing` sentinels (in a single-expression attribute, `null`/`undefined`
62
- * REMOVE the attribute; in a child, they clear it), no sanitizer indirection, no async parts, no
63
- * dev-mode branches.
64
- *
65
- * Known limits, deliberate and shared with lit-html's envelope: no bindings inside comments (the
66
- * value is consumed and ignored), no dynamic tag names, and nested `<template>` elements' contents
67
- * are not traversed.
68
- *
69
- * CONTRACTS THE SPEED PAYS FOR — these are the trade, documented rather than discovered:
70
- *
71
- * - **The renderer owns its container below the mount point.** The whole-range fast clear wipes
72
- * everything in a parent the part fully owns, including nodes user code appended there by hand
73
- * (lit-html would preserve them). Same contract as mounting Vue or React into a container.
74
- * - **Do not call `Node.normalize()` on rendered content.** Child anchors are text nodes, and
75
- * normalize merges adjacent text — lit-html's comment anchors are immune to this; ours are not.
76
- * - **A plain string renders as text, never as HTML.** The Reef renderer parsed strings as markup;
77
- * this one has no innerHTML sink at all (an XSS class removed). The deliberate escape hatch for
78
- * trusted markup is a property binding: `.innerHTML=${trusted}`.
79
- * - **Hydration is automatic and markerless.** The first render into a container that already has
80
- * children adopts them as server output of the same template (statics matched byte-for-byte,
81
- * anchors installed by splitting live text at known value positions), falling back to a clean
82
- * render on any mismatch. Requires the initial client render to match server state — same
83
- * contract as React/Vue hydration.
84
- * - **No directive protocol.** The template language itself is closed to extension — Vera extends
85
- * at the framework layer (inserts) and through element refs, not inside the renderer's value
86
- * handling.
87
- * - Event handlers are invoked with `this` bound to the ELEMENT (lit binds its host).
88
- *
89
- * NAMING NOTE: internal class fields and methods are `_`-prefixed because the production build
90
- * mangles properties matching /^_[a-z]/ (see defaultRollupConfig). That is what lets this file use
91
- * full descriptive names while still shipping one-letter properties — locals and top-level names
92
- * are mangled by default anyway, but property names are not. `_$litType$` and `handleEvent`
93
- * deliberately do not match the pattern: the first is an interop wire format, the second is called
94
- * by the DOM itself.
51
+ * Internal members are `_`-prefixed because the production build mangles `/^_[a-z]/`. `$`-named
52
+ * members cross bundle boundaries (keyed, spread, slots) and survive mangling by not matching it.
95
53
  */
96
54
 
97
55
  /**
98
- * Preserves the DOM of templates a child position toggles away from, instead of destroying it —
99
- * form values, scroll positions and media playback survive the round trip (lit-html calls this
100
- * `cache`). Stashed DOM is parked in its instance's own fragment and re-adopted on return.
56
+ * Preserves the DOM of a template a position toggles away from, instead of destroying it — form values
57
+ * and media state survive the round trip. Anything that is not a template passes straight through, so
58
+ * `hold(editing && editor())` is fine.
101
59
  *
102
60
  * ```js
103
61
  * html`<div>${hold(editing ? editor() : viewer())}</div>`
104
62
  * ```
105
- *
106
- * **Anything that is not a template passes straight through.** There is nothing to park for a
107
- * string, a list, `null` or `false`, and the branch that produces one is the ordinary shape of the
108
- * expression this wraps — `hold(editing && editor())`, `hold(row ?? null)`. Wrapping those handed
109
- * the renderer a `{ $h }` carrying a non-template, which reached the held-commit path and threw on
110
- * `result.strings`: a whole render lost, from a value the same expression renders happily one
111
- * character to the left. Decided here rather than in the renderer so the hot path pays nothing.
112
63
  */
113
64
  declare const hold: <T>(result: T) => T | {
114
65
  $h: TemplateResult;
115
66
  };
67
+ declare const renderInto: (result: unknown, container: Node, owns?: boolean) => void;
68
+ type Registry = {
69
+ get(name: never): unknown;
70
+ $S?: unknown;
71
+ $F?: unknown;
72
+ };
116
73
  /**
117
- * Writes a template result into a container. The renderer's imperative draw: no reactivity, no
118
- * lifecycle, no knowledge of components. Slots into Vera via `wire([renderer])`; core's built-in
119
- * `html` tag already produces the accepted shape, so no `setHtml` call is required — though
120
- * lit-html's `html` also works, its results being structurally identical.
121
- *
122
- * **It owns its own range and nothing else.** The first call appends a marker and anchors a root
123
- * part there; later calls with the same container reuse that part and walk only the value slots, so
124
- * nodes are updated in place rather than rebuilt. Content that was already in the container stays.
125
- *
126
- * **Named for the relationship, not the act.** It was `render` until 0.2.0, which collided with
127
- * core's `render` — a different function, with a different arity, that declares a *reactive*
128
- * template and commits a component's setup. Both were public and both were documented, so a reader
129
- * who knew one misread the other. `renderElement` and `renderDom` were considered and rejected: this
130
- * renders *into* a container, and the container is a `Node` — a shadow root and a fragment are both
131
- * valid, so "element" would be a lie in the type. Argument order is lit-html's on purpose.
132
- *
133
- * HYDRATION lives in `@verajs/renderer/hydrate` — a drop-in superset entry whose `renderInto` adopts
134
- * existing server-rendered children on first render. SSR apps import from there instead of here;
135
- * this entry carries zero hydration code.
74
+ * What a consumer's TypeScript sees — the shape `wire` accepts (`Wireable`, structurally: this package imports no
75
+ * types from `@verajs/inserts`): a DESCRIPTOR, `on: 'render'`, callable with options to give `[renderer, a connector]`.
76
+ * On a server `on` is in fact `undefined` (decided at load, below) — a runtime decision the type does not carry, as
77
+ * the previous `on: 'render' | undefined` did: that matched neither a descriptor nor a connector, so `wire([renderer])`
78
+ * stopped compiling in a consumer's project (tests/consumer, 2026-10-10).
136
79
  */
137
- declare const renderInto: (result: unknown, container: Node) => void;
138
- declare const renderer: {
139
- name: string;
140
- on: "render";
80
+ type RendererModule = ((options?: {
81
+ shadow?: 'open' | 'closed' | false | ShadowRootInit;
82
+ foreignNodes?: 'preserve' | 'drop';
83
+ }) => readonly [RendererModule, (registry: Registry) => void]) & {
84
+ readonly on: 'render';
141
85
  fn: never;
142
86
  priority: number;
143
- /**
144
- * Typed against the registry `wire` actually hands over, not a narrower shape that happens to
145
- * describe the one lookup this makes. A structural `{ get(name: 'value'): … }` is **not**
146
- * assignable from `Inserts`, so `wire([renderer])` failed to compile in a consumer's project while
147
- * this repo's own typecheck — which reads sources, not the shipped `.d.ts` — saw nothing.
148
- */
149
- connect: (given: {
150
- get(name: never): unknown;
151
- }) => void;
87
+ connect: (given: Registry) => void;
152
88
  };
89
+ /**
90
+ * **`renderer` is a DUAL** — `wire([renderer])` as it always was, or `wire([renderer({ shadow: 'open' })])` to set the
91
+ * app's default root: every component whose own `shadow` option says nothing gets it (core's `init` reads it after the
92
+ * component's own and before light DOM). `renderer({ foreignNodes: 'preserve' })` is the same for `foreignNodes`, and sets
93
+ * COMPONENT roots only — a container handed to `renderInto` (`document.body`, `#app`) always keeps foreign nodes. Called, it returns `[renderer, a connector setting the default]` — `wire`
94
+ * takes nested arrays — so the module is one function with its descriptor fields on it, and nothing is made per call
95
+ * but that connector.
96
+ *
97
+ * **On a server it declines its render insert** (Brian's (b′), 2026-10-10): `@verajs/ssr` renders with its own renderer,
98
+ * and a client one wired in shared app code used to DISPLACE it, breaking every server render. There `on` is undefined,
99
+ * which makes `wire` hand this function the registry as a CONNECTOR: it still CONNECTS — the registry, `untracked`, the
100
+ * hydration hand-off: a process that loaded ssr may install a client DOM and call renderInto directly (tests/spread-ssr
101
+ * does) — and only the render INSERT is declined, so one shared `wire([renderer({ shadow })])` carries the same default
102
+ * to both sides. Development says so once per process.
103
+ */
104
+ declare const renderer: RendererModule;
153
105
 
154
106
  export { hold, renderInto, renderer };
155
107
  export type { TemplateResult };
@@ -1 +1 @@
1
- {"version":3,"file":"vera-renderer.d.ts","sources":["../../src/types.ts","../../src/renderer.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBG;;;;;;;;;;;;;;;;;;;ACjBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;;;;;;;;;;;;;;;;AAwBA;AACH;AAEI,kBAAgC;sBACvB;AAEb;;AA+cM;AAEN;AAEA;AAEA;AACE;;AAsBA;AACE;AACA;;;AAGA;AACA;AACA;AACE;;;AAEA;;AAGF;;;;;AAKG;AACH;;AAEA;AACA;;AAEE;AACE;AACA;;AAEJ;AACA;;;;","names":[]}
1
+ {"version":3,"file":"vera-renderer.d.ts","sources":["../../src/types.ts","../../src/renderer.ts"],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBG;;;;;;;;;;;;;;;;;;;ACjBH;;;;;;;;;;;;;;;;AAgBG;;AA2PC;;;;AAIG;AACH;AACA;AACA;;cAEE,IAAI;sBACM;AACV;AAYC,cAAA,UAAA,+BAAA,IAAA;AACH,KAAA;;;;;;;AAOE;AACA;;;AAEA;mBACI;yCACU,cAAA;;AAEd,gBAAI,cAA8B,aAAA,QAAA;AAClC;AACE;;qBACsC,QAAM;AAC5C;AACA;AACE;;AACK;;;AAEH;AACE;;;;AAIG;AACH;;;sCAGE;;;;","names":[]}