@gyral/core 0.2.0 → 0.3.1

package/dist/view/template-element.js

@@ -0,0 +1,45 @@
+// One <template> element per template object, created on first use (view/01-templates.md
+// "Instantiation"). The browser's own parser builds it from the template HTML; the runtime
+// preparer then checks the parse (rule 7). Server templates never get one (rule 11). An svg
+// template's is prepared by `svgTemplate` when its first result is made (template.ts `svg`), so
+// apps without svg templates don't carry that code. Both parse through the `gyral` Trusted Types
+// policy (trusted-html.ts).
+import { verify } from '#prepare';
+import { DEV } from '#view-dev';
+import { message } from './message.js';
+import { SERVER_ONLY, TemplateError } from './normalize/errors.js';
+import { trustedHTML } from './trusted-html.js';
+const elements = new WeakMap();
+/** The cached <template> element for `template`, parsed (and checked) on first use. */
+export function templateElement(template) {
+    const cached = elements.get(template);
+    if (cached !== undefined)
+        return cached;
+    if (template.server) {
+        // Production keeps a short message: the class and its explanation stay out of the bundle.
+        throw DEV ? new TemplateError(11, SERVER_ONLY, template.loc) : new Error(message(71));
+    }
+    const el = document.createElement('template');
+    el.innerHTML = trustedHTML(template.html);
+    verify(template, el);
+    elements.set(template, el);
+    return el;
+}
+/**
+ * Prepares an svg template's <template> element (01 "svg templates"): its HTML is parsed inside
+ * an <svg>, so the parser creates SVG elements (camelCase names and attributes, namespaced
+ * static attributes), and that <svg>'s children become the content. Called with every svg
+ * result, before anything renders it; outside a document (the server) there is nothing to do.
+ */
+export function svgTemplate(template) {
+    if (elements.has(template) || typeof document === 'undefined')
+        return;
+    const el = document.createElement('template');
+    el.innerHTML = trustedHTML(`<svg>${template.html}</svg>`);
+    const content = el.content;
+    // Anything the parser moved out of the <svg> is dropped here, and the check reports it.
+    content.replaceChildren(...content.firstChild.childNodes);
+    verify(template, el);
+    elements.set(template, el);
+}
+//# sourceMappingURL=template-element.js.map

package/dist/view/template-element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-element.js","sourceRoot":"","sources":["../../src/view/template-element.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,2FAA2F;AAC3F,4FAA4F;AAC5F,gGAAgG;AAChG,iGAAiG;AACjG,4BAA4B;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAuC,CAAC;AAEpE,uFAAuF;AACvF,MAAM,UAAU,eAAe,CAAC,QAAwB;IACtD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpB,0FAA0F;QAC1F,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,EAAE,EAAE,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9C,EAAE,CAAC,SAAS,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,QAAwB;IAClD,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO;IACtE,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9C,EAAE,CAAC,SAAS,GAAG,WAAW,CAAC,QAAQ,QAAQ,CAAC,IAAI,QAAQ,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC;IAC3B,wFAAwF;IACxF,OAAO,CAAC,eAAe,CAAC,GAAI,OAAO,CAAC,UAAsB,CAAC,UAAU,CAAC,CAAC;IACvE,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC","sourcesContent":["// One <template> element per template object, created on first use (view/01-templates.md\n// \"Instantiation\"). The browser's own parser builds it from the template HTML; the runtime\n// preparer then checks the parse (rule 7). Server templates never get one (rule 11). An svg\n// template's is prepared by `svgTemplate` when its first result is made (template.ts `svg`), so\n// apps without svg templates don't carry that code. Both parse through the `gyral` Trusted Types\n// policy (trusted-html.ts).\nimport { verify } from '#prepare';\nimport { DEV } from '#view-dev';\nimport { message } from './message.js';\nimport { SERVER_ONLY, TemplateError } from './normalize/errors.js';\nimport type { TemplateObject } from './normalize/types.js';\nimport { trustedHTML } from './trusted-html.js';\n\nconst elements = new WeakMap<TemplateObject, HTMLTemplateElement>();\n\n/** The cached <template> element for `template`, parsed (and checked) on first use. */\nexport function templateElement(template: TemplateObject): HTMLTemplateElement {\n  const cached = elements.get(template);\n  if (cached !== undefined) return cached;\n  if (template.server) {\n    // Production keeps a short message: the class and its explanation stay out of the bundle.\n    throw DEV ? new TemplateError(11, SERVER_ONLY, template.loc) : new Error(message(71));\n  }\n  const el = document.createElement('template');\n  el.innerHTML = trustedHTML(template.html);\n  verify(template, el);\n  elements.set(template, el);\n  return el;\n}\n\n/**\n * Prepares an svg template's <template> element (01 \"svg templates\"): its HTML is parsed inside\n * an <svg>, so the parser creates SVG elements (camelCase names and attributes, namespaced\n * static attributes), and that <svg>'s children become the content. Called with every svg\n * result, before anything renders it; outside a document (the server) there is nothing to do.\n */\nexport function svgTemplate(template: TemplateObject): void {\n  if (elements.has(template) || typeof document === 'undefined') return;\n  const el = document.createElement('template');\n  el.innerHTML = trustedHTML(`<svg>${template.html}</svg>`);\n  const content = el.content;\n  // Anything the parser moved out of the <svg> is dropped here, and the check reports it.\n  content.replaceChildren(...(content.firstChild as Element).childNodes);\n  verify(template, el);\n  elements.set(template, el);\n}\n"]}

package/dist/view/template.d.ts

@@ -0,0 +1,29 @@
+import type { TemplateObject } from './normalize/types.js';
+declare const SOURCE: unique symbol;
+/** What `html` returns: a template plus this render's values. */
+export interface TemplateResult {
+    readonly [SOURCE]: readonly string[] | TemplateObject;
+    readonly values: readonly unknown[];
+}
+/** The template tag: `` html`<p>${s.text}</p>` ``. */
+export declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult;
+/**
+ * The SVG fragment tag: `` svg`<path d=${s.d} />` ``. Its top level is SVG content, so it
+ * renders only inside an `<svg>` (or another SVG element) of an html template
+ * (view/01-templates.md "svg templates"). A whole `<svg>` graphic is written with html.
+ */
+export declare const svg: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult;
+/** Internal: what the template compiler (`@gyral/core/vite`) rewrites `html` calls into. */
+export declare function compiled(template: TemplateObject, values: readonly unknown[]): TemplateResult;
+/** Internal: what the template compiler rewrites `svg` calls into. */
+export declare function compiledSvg(template: TemplateObject, values: readonly unknown[]): TemplateResult;
+export declare function isTemplateResult(value: unknown): value is TemplateResult;
+/** Internal: a result's source, compared by identity to skip `templateOf` on updates. */
+export declare const sourceOf: (result: TemplateResult) => readonly string[] | TemplateObject;
+/**
+ * The template object of a result: compiled results carry it; a runtime result's call site is
+ * normalized once by `#prepare` (cached there, so compiled builds carry neither the preparer
+ * nor its cache).
+ */
+export declare function templateOf(result: TemplateResult): TemplateObject;
+export {};

package/dist/view/template.js

@@ -0,0 +1,84 @@
+// Template results and the `html` and `svg` tags (view/01-templates.md "Authoring", "Template
+// results", "svg templates"). A result is a template source (the call site's strings, or a
+// template object) plus this call's values, recognised by a module-private symbol so data from
+// JSON can never pass for one. `templateOf` turns the source into the template object: compiled
+// and svg results carry it, html results are normalized once per strings array through
+// `#prepare` (prepare.ts). Development records each call site's source location (loc.ts) for
+// error messages.
+import { prepare } from '#prepare';
+import { DEV } from '#view-dev';
+import { callSite, locOf, setLoc } from './loc.js';
+import { svgTemplate } from './template-element.js';
+const SOURCE = Symbol('gyral.template');
+/** The template tag, as `html` is in production. */
+function tag(strings, ...values) {
+    // Development: the call site, from the stack, the first time (unless `html.at` gave it).
+    if (DEV && locOf(strings) === undefined)
+        setLoc(strings, callSite(new Error().stack));
+    return { [SOURCE]: strings, values };
+}
+/** The svg tag, as `svg` is in production: svg results carry their (prepared) template. */
+function svgTag(strings, ...values) {
+    // Development: the call site, from the stack, the first time (unless `svg.at` gave it), so
+    // the normalizer's rule errors name it.
+    if (DEV && locOf(strings) === undefined)
+        setLoc(strings, callSite(new Error().stack));
+    return compiledSvg(prepare(strings, true), values);
+}
+/**
+ * Development: `html.at(loc)` (and `svg.at(loc)`) is the tag with a known call site. The Vite
+ * preset's dev transform (compiler/locate.ts) writes it at every call site, since stack
+ * positions in transformed modules aren't the author's lines. Attached here, not by a statement
+ * that mentions the tag, so production builds don't keep it alive (the compiler checks that).
+ */
+function withAt(html) {
+    const tags = new Map();
+    const at = (loc) => {
+        let located = tags.get(loc);
+        if (located === undefined) {
+            located = (strings, ...values) => {
+                setLoc(strings, loc);
+                return html(strings, ...values);
+            };
+            tags.set(loc, located);
+        }
+        return located;
+    };
+    return Object.assign(html, { at });
+}
+/** The template tag: `` html`<p>${s.text}</p>` ``. */
+export const html = DEV
+    ? withAt(tag)
+    : tag;
+/**
+ * The SVG fragment tag: `` svg`<path d=${s.d} />` ``. Its top level is SVG content, so it
+ * renders only inside an `<svg>` (or another SVG element) of an html template
+ * (view/01-templates.md "svg templates"). A whole `<svg>` graphic is written with html.
+ */
+export const svg = DEV
+    ? withAt(svgTag)
+    : svgTag;
+/** Internal: what the template compiler (`@gyral/core/vite`) rewrites `html` calls into. */
+export function compiled(template, values) {
+    return { [SOURCE]: template, values };
+}
+/** Internal: what the template compiler rewrites `svg` calls into. */
+export function compiledSvg(template, values) {
+    svgTemplate(template);
+    return { [SOURCE]: template, values };
+}
+export function isTemplateResult(value) {
+    return typeof value === 'object' && value !== null && SOURCE in value;
+}
+/** Internal: a result's source, compared by identity to skip `templateOf` on updates. */
+export const sourceOf = (result) => result[SOURCE];
+/**
+ * The template object of a result: compiled results carry it; a runtime result's call site is
+ * normalized once by `#prepare` (cached there, so compiled builds carry neither the preparer
+ * nor its cache).
+ */
+export function templateOf(result) {
+    const source = result[SOURCE];
+    return Array.isArray(source) ? prepare(source) : source;
+}
+//# sourceMappingURL=template.js.map

package/dist/view/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/view/template.ts"],"names":[],"mappings":"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","sourcesContent":["// Template results and the `html` and `svg` tags (view/01-templates.md \"Authoring\", \"Template\n// results\", \"svg templates\"). A result is a template source (the call site's strings, or a\n// template object) plus this call's values, recognised by a module-private symbol so data from\n// JSON can never pass for one. `templateOf` turns the source into the template object: compiled\n// and svg results carry it, html results are normalized once per strings array through\n// `#prepare` (prepare.ts). Development records each call site's source location (loc.ts) for\n// error messages.\nimport { prepare } from '#prepare';\nimport { DEV } from '#view-dev';\nimport { callSite, locOf, setLoc } from './loc.js';\nimport type { TemplateObject } from './normalize/types.js';\nimport { svgTemplate } from './template-element.js';\n\nconst SOURCE: unique symbol = Symbol('gyral.template');\n\n/** What `html` returns: a template plus this render's values. */\nexport interface TemplateResult {\n  readonly [SOURCE]: readonly string[] | TemplateObject;\n  readonly values: readonly unknown[];\n}\n\n/** The template tag, as `html` is in production. */\nfunction tag(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult {\n  // Development: the call site, from the stack, the first time (unless `html.at` gave it).\n  if (DEV && locOf(strings) === undefined) setLoc(strings, callSite(new Error().stack));\n  return { [SOURCE]: strings, values };\n}\n\n/** The svg tag, as `svg` is in production: svg results carry their (prepared) template. */\nfunction svgTag(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult {\n  // Development: the call site, from the stack, the first time (unless `svg.at` gave it), so\n  // the normalizer's rule errors name it.\n  if (DEV && locOf(strings) === undefined) setLoc(strings, callSite(new Error().stack));\n  return compiledSvg(prepare(strings, true), values);\n}\n\ntype Tag = typeof tag;\n\n/**\n * Development: `html.at(loc)` (and `svg.at(loc)`) is the tag with a known call site. The Vite\n * preset's dev transform (compiler/locate.ts) writes it at every call site, since stack\n * positions in transformed modules aren't the author's lines. Attached here, not by a statement\n * that mentions the tag, so production builds don't keep it alive (the compiler checks that).\n */\nfunction withAt(html: Tag): Tag {\n  const tags = new Map<string, Tag>();\n  const at = (loc: string): Tag => {\n    let located = tags.get(loc);\n    if (located === undefined) {\n      located = (strings, ...values) => {\n        setLoc(strings, loc);\n        return html(strings, ...values);\n      };\n      tags.set(loc, located);\n    }\n    return located;\n  };\n  return Object.assign(html, { at });\n}\n\n/** The template tag: `` html`<p>${s.text}</p>` ``. */\nexport const html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult = DEV\n  ? withAt(tag)\n  : tag;\n\n/**\n * The SVG fragment tag: `` svg`<path d=${s.d} />` ``. Its top level is SVG content, so it\n * renders only inside an `<svg>` (or another SVG element) of an html template\n * (view/01-templates.md \"svg templates\"). A whole `<svg>` graphic is written with html.\n */\nexport const svg: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult = DEV\n  ? withAt(svgTag)\n  : svgTag;\n\n/** Internal: what the template compiler (`@gyral/core/vite`) rewrites `html` calls into. */\nexport function compiled(template: TemplateObject, values: readonly unknown[]): TemplateResult {\n  return { [SOURCE]: template, values };\n}\n\n/** Internal: what the template compiler rewrites `svg` calls into. */\nexport function compiledSvg(template: TemplateObject, values: readonly unknown[]): TemplateResult {\n  svgTemplate(template);\n  return { [SOURCE]: template, values };\n}\n\nexport function isTemplateResult(value: unknown): value is TemplateResult {\n  return typeof value === 'object' && value !== null && SOURCE in value;\n}\n\n/** Internal: a result's source, compared by identity to skip `templateOf` on updates. */\nexport const sourceOf = (result: TemplateResult): readonly string[] | TemplateObject =>\n  result[SOURCE];\n\n/**\n * The template object of a result: compiled results carry it; a runtime result's call site is\n * normalized once by `#prepare` (cached there, so compiled builds carry neither the preparer\n * nor its cache).\n */\nexport function templateOf(result: TemplateResult): TemplateObject {\n  const source = result[SOURCE];\n  return Array.isArray(source) ? prepare(source) : (source as TemplateObject);\n}\n"]}

package/dist/view/trusted-html.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `html` as an HTML sink accepts it: a `TrustedHTML` from the `gyral` policy where the browser
+ * has Trusted Types, the string itself elsewhere. Typed as `string` because lib.dom's
+ * `innerHTML` setter takes only strings; the browser stringifies a `TrustedHTML` to the same text.
+ */
+export declare function trustedHTML(html: string): string;

package/dist/view/trusted-html.js

@@ -0,0 +1,34 @@
+// Trusted Types (view/01-templates.md "Instantiation", gyral-ei9): a document whose CSP says
+// `require-trusted-types-for 'script'` refuses plain strings at HTML sinks such as `innerHTML`.
+// The browser parses only two kinds of HTML for Gyral: a template's HTML, which is the author's
+// own template strings (holes are markers, never values), and `raw()` markup, trusted by
+// contract (view/02 "raw(html)"). Both go through one policy named `gyral`, created on first use
+// where the browser has Trusted Types; an app allows it with `trusted-types gyral`. On first use
+// rather than at import, so a policy that refuses the name fails where HTML is parsed, not when
+// a module loads. A CSP whose `trusted-types` list leaves `gyral` out (with or without
+// enforcement) makes `createPolicy` throw: Gyral then parses plain strings, as before Trusted
+// Types, and warns in development; where Trusted Types are enforced the sink reports it.
+import { DEV } from '#view-dev';
+import { message } from './message.js';
+const passThrough = { createHTML: (input) => input };
+let policy;
+/**
+ * `html` as an HTML sink accepts it: a `TrustedHTML` from the `gyral` policy where the browser
+ * has Trusted Types, the string itself elsewhere. Typed as `string` because lib.dom's
+ * `innerHTML` setter takes only strings; the browser stringifies a `TrustedHTML` to the same text.
+ */
+export function trustedHTML(html) {
+    policy ??= create();
+    return policy.createHTML(html);
+}
+function create() {
+    try {
+        return (globalThis.trustedTypes?.createPolicy('gyral', passThrough) ?? passThrough);
+    }
+    catch (error) {
+        if (DEV)
+            console.warn(message(72), error);
+        return passThrough;
+    }
+}
+//# sourceMappingURL=trusted-html.js.map

package/dist/view/trusted-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-html.js","sourceRoot":"","sources":["../../src/view/trusted-html.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,gGAAgG;AAChG,gGAAgG;AAChG,yFAAyF;AACzF,iGAAiG;AACjG,iGAAiG;AACjG,gGAAgG;AAChG,uFAAuF;AACvF,8FAA8F;AAC9F,yFAAyF;AACzF,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAUvC,MAAM,WAAW,GAAW,EAAE,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC;AAE7D,IAAI,MAA0B,CAAC;AAE/B;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,KAAK,MAAM,EAAE,CAAC;IACpB,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,MAAM;IACb,IAAI,CAAC;QACH,OAAO,CACJ,UAA+C,CAAC,YAAY,EAAE,YAAY,CACzE,OAAO,EACP,WAAW,CACZ,IAAI,WAAW,CACjB,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,GAAG;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QAC1C,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC","sourcesContent":["// Trusted Types (view/01-templates.md \"Instantiation\", gyral-ei9): a document whose CSP says\n// `require-trusted-types-for 'script'` refuses plain strings at HTML sinks such as `innerHTML`.\n// The browser parses only two kinds of HTML for Gyral: a template's HTML, which is the author's\n// own template strings (holes are markers, never values), and `raw()` markup, trusted by\n// contract (view/02 \"raw(html)\"). Both go through one policy named `gyral`, created on first use\n// where the browser has Trusted Types; an app allows it with `trusted-types gyral`. On first use\n// rather than at import, so a policy that refuses the name fails where HTML is parsed, not when\n// a module loads. A CSP whose `trusted-types` list leaves `gyral` out (with or without\n// enforcement) makes `createPolicy` throw: Gyral then parses plain strings, as before Trusted\n// Types, and warns in development; where Trusted Types are enforced the sink reports it.\nimport { DEV } from '#view-dev';\nimport { message } from './message.js';\n\ninterface Policy {\n  createHTML(input: string): string;\n}\n\ninterface PolicyFactory {\n  createPolicy(name: string, rules: Policy): Policy;\n}\n\nconst passThrough: Policy = { createHTML: (input) => input };\n\nlet policy: Policy | undefined;\n\n/**\n * `html` as an HTML sink accepts it: a `TrustedHTML` from the `gyral` policy where the browser\n * has Trusted Types, the string itself elsewhere. Typed as `string` because lib.dom's\n * `innerHTML` setter takes only strings; the browser stringifies a `TrustedHTML` to the same text.\n */\nexport function trustedHTML(html: string): string {\n  policy ??= create();\n  return policy.createHTML(html);\n}\n\nfunction create(): Policy {\n  try {\n    return (\n      (globalThis as { trustedTypes?: PolicyFactory }).trustedTypes?.createPolicy(\n        'gyral',\n        passThrough,\n      ) ?? passThrough\n    );\n  } catch (error) {\n    if (DEV) console.warn(message(72), error);\n    return passThrough;\n  }\n}\n"]}

package/dist/vite.d.ts

@@ -1,18 +1,62 @@
-/** Every Lit package: resolve exactly one copy, even when Gyral is linked from elsewhere. */
-export declare const LIT_PACKAGES: readonly string[];
-/**
- * Lit modules that Gyral imports or re-exports. Pre-bundling them up front stops Vite from
- * discovering them mid-run, which reloads the page and fails the first browser test run.
- */
-export declare const LIT_PREBUNDLE: readonly string[];
+import type { Plugin } from 'vite';
+export interface TemplateCompilerOptions {
+    /**
+     * Module specifiers whose `html` (and `svg`) exports are the view layer's tags (default
+     * `DEFAULT_TEMPLATE_SOURCES`). An import matches when its specifier is listed, or when it
+     * resolves to the same module as a listed one; core's own view modules always match. A
+     * source other than '@gyral/core' must also export `compiled` (and `compiledSvg` when it
+     * exports `svg`).
+     */
+    readonly sources?: readonly string[];
+    /**
+     * Rule 7's extra check with parse5 (an optional peer dependency): `true` (default) uses
+     * 'parse5' when it is installed, a string names the module to load, `false` skips it.
+     */
+    readonly parse5?: boolean | string;
+}
+/** Where the preset looks for components and writes their typings (gyral-1zd.25). */
+export interface ElementTypesOptions {
+    /** Source directories to scan, relative to the Vite root. Default `['src']`. */
+    readonly dirs?: readonly string[];
+    /** The declaration file to write, relative to the Vite root. Default `.gyral/elements.d.ts`. */
+    readonly out?: string;
+}
 export interface GyralViteOptions {
-    /** More modules to pre-bundle (e.g. 'lit/directives/unsafe-html.js'). */
+    /**
+     * Generated element typings (`.gyral/elements.d.ts`, see `ElementTypesOptions`), or `false`
+     * to write none. Default: on, scanning `src`.
+     */
+    readonly types?: ElementTypesOptions | false;
+    /** Modules to pre-bundle in dev, so Vite doesn't discover them mid-run and reload. */
     readonly optimize?: readonly string[];
+    /** Template compiler options (`vite build` only). */
+    readonly compiler?: TemplateCompilerOptions;
+    /**
+     * The app is never server-rendered: leave the hydration code out of the browser bundle
+     * (`gyralClientOnly()`, view/07-hydration.md "Client-only builds"). Default false.
+     */
+    readonly clientOnly?: boolean;
+    /**
+     * Automatic component loading (ADR 0016 addendum): every component defined under `include`
+     * gets a client module the build splits out, and a loader (`virtual:gyral/components`, added
+     * to the client build's input) imports a tag's module once that tag is in the page.
+     * `renderPage({ components })` then links exactly the components a page rendered, so pages
+     * need no client entry of their own and no side-effect imports. Default off.
+     */
+    readonly components?: boolean | ComponentsOptions;
+}
+export interface ComponentsOptions {
+    /** Directories (relative to Vite's root) whose modules' `define()` tags are found. Default `['src']`. */
+    readonly include?: readonly string[];
+    /**
+     * Tag → module (relative to Vite's root) for components the scan can't find: those defined
+     * through a wrapper such as `defineMemberForm({ tag: 'member-form' })`, which calls
+     * `define()` itself. Listed entries win over scanned ones.
+     */
+    readonly modules?: Readonly<Record<string, string>>;
 }
 export interface GyralViteConfig {
-    readonly resolve: {
-        readonly dedupe: string[];
-    };
+    readonly plugins: Plugin[];
     readonly optimizeDeps: {
         readonly include: string[];
     };
@@ -21,5 +65,7 @@ export interface GyralViteConfig {
  * Spread into a Vite config, or into each Vitest project:
  *
  *   export default defineConfig({ ...gyralVitePreset(), build: { … } });
+ *
+ * With plugins of your own, list both: `plugins: [...preset.plugins, mine()]`.
  */
 export declare function gyralVitePreset(options?: GyralViteOptions): GyralViteConfig;