@gyral/core 0.2.0 → 0.3.1

package/dist/compiler/features.d.ts

@@ -0,0 +1,34 @@
+import { langOf } from './ast.js';
+import { type Feature } from './facts.js';
+export type { Feature } from './facts.js';
+/**
+ * Text a module must contain to use a feature (the plugins' transform filters list the same).
+ * `invokers`: also any import or export, which may reach `raw`.
+ */
+export declare const FEATURE_HINTS: Readonly<Record<Feature, RegExp>>;
+/** A plugin context's `resolve`, as far as detection needs it. */
+type Resolve = (source: string, importer: string) => Promise<{
+    readonly id: string;
+} | null>;
+/** What the scan needs from the transform hook's plugin context. */
+export interface ScanContext {
+    /** `this.parse` (Rolldown's parser, TypeScript included). */
+    readonly parse: (code: string, lang: ReturnType<typeof langOf>) => unknown;
+    readonly resolve: Resolve;
+}
+export interface FeatureHooks {
+    /** Finds the core copy the app imports (its compiled entry), to register with and to skip. */
+    buildStart(resolve: Resolve, root: string): Promise<void>;
+    resolveId(source: string): {
+        id: string;
+        moduleSideEffects: true;
+    } | null;
+    load(id: string): string | null;
+    /** The imports to append to module `id` for the features its `code` may use; '' for none. */
+    inject(code: string, id: string, context: ScanContext): Promise<string>;
+}
+/**
+ * Detection for `features`. `ownEntry`: the compiled entry of the core copy running the plugin,
+ * used when the app's root can't resolve `@gyral/core/compiled` (fixtures, unusual layouts).
+ */
+export declare function createFeatures(features: readonly Feature[], ownEntry: string): FeatureHooks;

package/dist/compiler/features.js

@@ -0,0 +1,158 @@
+// Build-time feature detection (view/05-element.md "Features register themselves",
+// gyral-c5d.11, gyral-c5d.12), loaded lazily by the plugin shells in ../vite.ts. Some optional
+// machinery can't register itself from an API call, because apps reach it through plain data:
+// spec fields (`viewTransition`, `renderOnFrame`, `states`, `subscriptions`) and markup (`data-intent-on`
+// values, `raw()` content). In builds that leave that machinery out by default (the
+// `gyral-compiled` condition, and `gyral-client-only` for the invoker fallback), the modules
+// that can affect Gyral components are scanned, and a module that may use a feature gets one
+// import added at its end: `virtual:gyral-use/<feature>`, a side-effect module that calls
+// `register()` from core's `use-<feature>` module before any module that imports it runs. The
+// registration modules are reached only this way, never from an entry, so a build that doesn't
+// use a feature doesn't even load its code (Rolldown emits chunks for every import() it loads,
+// tree-shaken or not).
+//
+// Which modules (scope.ts): the app's own source, and installed packages that are Gyral's or
+// depend on one, directly or through their dependencies. What counts in them (facts.ts): names
+// and strings in the module's AST, never comments, and `raw` only when it comes from
+// `@gyral/core`. Both over-approximate, so the scan stays sound: a field or event can only be
+// set by writing its name somewhere, in a module that can reach Gyral (a name built at run
+// time, such as `{ ['sta' + 'tes']: … }`, or spec data written in a package that doesn't
+// depend on Gyral, are the gaps; view/05 says what then degrades). A false positive only bundles a few hundred
+// bytes that weren't needed. Core's own modules are skipped (they implement it); a module that
+// doesn't parse is matched on its text, comments included.
+import { join } from 'node:path';
+import { langOf } from './ast.js';
+import { factsOf, writes } from './facts.js';
+import { createScope } from './scope.js';
+/** The text fallback, for a module that doesn't parse: the 0.3.1-next.0 scan. */
+const TEXT_USES = {
+    invokers: /data-intent-command\s*=|data-intent-on\s*=\s*\\?["']?(?:[\w-]+\s+)*(?:command\b|\$\{)|(["'`])command\1|\braw\b\s*(?:\(|as\b)/i,
+    transitions: /\bviewTransition\b/,
+    frame: /\brenderOnFrame\b/,
+    states: /\bstates\b/,
+    forms: /\bformAssociated\b/,
+    subscriptions: /\bsubscriptions\b/,
+    dialogs: /\?(?:modal|popover-open)\s*=/i,
+    disposal: /\bdispose\b/,
+    errorView: /\berror\b/,
+    errored: /\bErrored\b/,
+};
+/** Each feature's registration module in core (`src/<name>.ts`, published as `dist/<name>.js`). */
+const REGISTRATION = {
+    invokers: 'use-invokers',
+    transitions: 'use-transitions',
+    frame: 'use-frame-lane',
+    states: 'use-states',
+    forms: 'use-form-associated',
+    subscriptions: 'use-subscriptions',
+    dialogs: 'use-dialogs',
+    disposal: 'use-disposal',
+    errorView: 'use-error-view',
+    errored: 'use-errored',
+};
+/**
+ * Text a module must contain to use a feature (the plugins' transform filters list the same).
+ * `invokers`: also any import or export, which may reach `raw`.
+ */
+export const FEATURE_HINTS = {
+    invokers: /data-intent-on|command|raw|import|export/i,
+    transitions: /viewTransition/,
+    frame: /renderOnFrame/,
+    states: /states/,
+    forms: /formAssociated/,
+    subscriptions: /subscriptions/,
+    dialogs: /modal|popover-open/i,
+    disposal: /dispose/,
+    errorView: /error/,
+    errored: /Errored/,
+};
+const PREFIX = 'virtual:gyral-use/';
+/** The package that exports `raw`. */
+const CORE = '@gyral/core';
+const RESOLVED = '\0gyral-use/';
+const SCRIPT = /\.[cm]?[jt]sx?$/;
+/** core's compiled entry, in its source tree or its published dist/: [, dir, extension]. */
+const ENTRY_FILE = /[\\/](src|dist)[\\/]view[\\/]compiled\.(ts|js)$/;
+const importsOf = (features) => features.map((feature) => `\nimport ${JSON.stringify(PREFIX + feature)};`).join('');
+/**
+ * Detection for `features`. `ownEntry`: the compiled entry of the core copy running the plugin,
+ * used when the app's root can't resolve `@gyral/core/compiled` (fixtures, unusual layouts).
+ */
+export function createFeatures(features, ownEntry) {
+    let entry = ownEntry;
+    let scope = createScope();
+    const skipped = new Set([ownEntry.replace(ENTRY_FILE, '/')]);
+    /** A registration module next to the compiled entry's view/ directory. */
+    const moduleOf = (name) => entry.replace(ENTRY_FILE, (_, dir, ext) => `/${dir}/${name}.${ext}`);
+    const isCore = (id) => [...skipped].some((dir) => id.startsWith(dir));
+    /**
+     * Whether one of `specifiers`, imported by `importer`, is a module of core (where `raw` comes
+     * from): `@gyral/core` or one of its subpaths, or a specifier that resolves into core (an
+     * alias, a path). Another package that re-exports core's `raw` counts in its own module.
+     */
+    async function coreAmong(specifiers, importer, resolve) {
+        for (const specifier of specifiers) {
+            if (specifier === CORE || specifier.startsWith(`${CORE}/`))
+                return true;
+            let resolved = null;
+            try {
+                resolved = await resolve(specifier, importer);
+            }
+            catch {
+                // unresolvable: the bundler reports it
+            }
+            const id = resolved?.id.replace(/\?.*$/, '');
+            if (id !== undefined && (isCore(id) || scope.packageOf(id) === CORE))
+                return true;
+        }
+        return false;
+    }
+    return {
+        async buildStart(resolve, root) {
+            scope = createScope(); // manifests may have changed since the last build (watch mode)
+            const resolved = await resolve('@gyral/core/compiled', join(root, 'index.html'));
+            if (resolved === null || !ENTRY_FILE.test(resolved.id))
+                return;
+            entry = resolved.id;
+            skipped.add(entry.replace(ENTRY_FILE, '/'));
+        },
+        resolveId(source) {
+            if (!source.startsWith(PREFIX))
+                return null;
+            const feature = source.slice(PREFIX.length);
+            return features.includes(feature)
+                ? { id: RESOLVED + feature, moduleSideEffects: true }
+                : null;
+        },
+        load(id) {
+            if (!id.startsWith(RESOLVED))
+                return null;
+            const file = moduleOf(REGISTRATION[id.slice(RESOLVED.length)]);
+            return `import { register } from ${JSON.stringify(file)};\nregister();\n`;
+        },
+        async inject(code, id, context) {
+            const file = id.replace(/\?.*$/, '');
+            if (id.startsWith('\0') || !SCRIPT.test(file) || isCore(file))
+                return '';
+            const hinted = features.filter((feature) => FEATURE_HINTS[feature].test(code));
+            if (hinted.length === 0 || !scope.inScope(file))
+                return '';
+            let program;
+            try {
+                program = context.parse(code, langOf(file));
+            }
+            catch {
+                return importsOf(hinted.filter((feature) => TEXT_USES[feature].test(code)));
+            }
+            const facts = factsOf(program);
+            const used = [];
+            for (const feature of hinted) {
+                if (writes(facts, feature) ||
+                    (feature === 'invokers' && (await coreAmong(facts.rawSources, id, context.resolve))))
+                    used.push(feature);
+            }
+            return importsOf(used);
+        },
+    };
+}
+//# sourceMappingURL=features.js.map

package/dist/compiler/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.js","sourceRoot":"","sources":["../../src/compiler/features.ts"],"names":[],"mappings":"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","sourcesContent":["// Build-time feature detection (view/05-element.md \"Features register themselves\",\n// gyral-c5d.11, gyral-c5d.12), loaded lazily by the plugin shells in ../vite.ts. Some optional\n// machinery can't register itself from an API call, because apps reach it through plain data:\n// spec fields (`viewTransition`, `renderOnFrame`, `states`, `subscriptions`) and markup (`data-intent-on`\n// values, `raw()` content). In builds that leave that machinery out by default (the\n// `gyral-compiled` condition, and `gyral-client-only` for the invoker fallback), the modules\n// that can affect Gyral components are scanned, and a module that may use a feature gets one\n// import added at its end: `virtual:gyral-use/<feature>`, a side-effect module that calls\n// `register()` from core's `use-<feature>` module before any module that imports it runs. The\n// registration modules are reached only this way, never from an entry, so a build that doesn't\n// use a feature doesn't even load its code (Rolldown emits chunks for every import() it loads,\n// tree-shaken or not).\n//\n// Which modules (scope.ts): the app's own source, and installed packages that are Gyral's or\n// depend on one, directly or through their dependencies. What counts in them (facts.ts): names\n// and strings in the module's AST, never comments, and `raw` only when it comes from\n// `@gyral/core`. Both over-approximate, so the scan stays sound: a field or event can only be\n// set by writing its name somewhere, in a module that can reach Gyral (a name built at run\n// time, such as `{ ['sta' + 'tes']: … }`, or spec data written in a package that doesn't\n// depend on Gyral, are the gaps; view/05 says what then degrades). A false positive only bundles a few hundred\n// bytes that weren't needed. Core's own modules are skipped (they implement it); a module that\n// doesn't parse is matched on its text, comments included.\nimport { join } from 'node:path';\nimport { langOf, type Node } from './ast.js';\nimport { factsOf, writes, type Feature } from './facts.js';\nimport { createScope, type Scope } from './scope.js';\n\nexport type { Feature } from './facts.js';\n\n/** The text fallback, for a module that doesn't parse: the 0.3.1-next.0 scan. */\nconst TEXT_USES: Readonly<Record<Feature, RegExp>> = {\n  invokers:\n    /data-intent-command\\s*=|data-intent-on\\s*=\\s*\\\\?[\"']?(?:[\\w-]+\\s+)*(?:command\\b|\\$\\{)|([\"'`])command\\1|\\braw\\b\\s*(?:\\(|as\\b)/i,\n  transitions: /\\bviewTransition\\b/,\n  frame: /\\brenderOnFrame\\b/,\n  states: /\\bstates\\b/,\n  forms: /\\bformAssociated\\b/,\n  subscriptions: /\\bsubscriptions\\b/,\n  dialogs: /\\?(?:modal|popover-open)\\s*=/i,\n  disposal: /\\bdispose\\b/,\n  errorView: /\\berror\\b/,\n  errored: /\\bErrored\\b/,\n};\n\n/** Each feature's registration module in core (`src/<name>.ts`, published as `dist/<name>.js`). */\nconst REGISTRATION: Readonly<Record<Feature, string>> = {\n  invokers: 'use-invokers',\n  transitions: 'use-transitions',\n  frame: 'use-frame-lane',\n  states: 'use-states',\n  forms: 'use-form-associated',\n  subscriptions: 'use-subscriptions',\n  dialogs: 'use-dialogs',\n  disposal: 'use-disposal',\n  errorView: 'use-error-view',\n  errored: 'use-errored',\n};\n\n/**\n * Text a module must contain to use a feature (the plugins' transform filters list the same).\n * `invokers`: also any import or export, which may reach `raw`.\n */\nexport const FEATURE_HINTS: Readonly<Record<Feature, RegExp>> = {\n  invokers: /data-intent-on|command|raw|import|export/i,\n  transitions: /viewTransition/,\n  frame: /renderOnFrame/,\n  states: /states/,\n  forms: /formAssociated/,\n  subscriptions: /subscriptions/,\n  dialogs: /modal|popover-open/i,\n  disposal: /dispose/,\n  errorView: /error/,\n  errored: /Errored/,\n};\n\nconst PREFIX = 'virtual:gyral-use/';\n/** The package that exports `raw`. */\nconst CORE = '@gyral/core';\nconst RESOLVED = '\\0gyral-use/';\nconst SCRIPT = /\\.[cm]?[jt]sx?$/;\n/** core's compiled entry, in its source tree or its published dist/: [, dir, extension]. */\nconst ENTRY_FILE = /[\\\\/](src|dist)[\\\\/]view[\\\\/]compiled\\.(ts|js)$/;\n\n/** A plugin context's `resolve`, as far as detection needs it. */\ntype Resolve = (source: string, importer: string) => Promise<{ readonly id: string } | null>;\n\n/** What the scan needs from the transform hook's plugin context. */\nexport interface ScanContext {\n  /** `this.parse` (Rolldown's parser, TypeScript included). */\n  readonly parse: (code: string, lang: ReturnType<typeof langOf>) => unknown;\n  readonly resolve: Resolve;\n}\n\nexport interface FeatureHooks {\n  /** Finds the core copy the app imports (its compiled entry), to register with and to skip. */\n  buildStart(resolve: Resolve, root: string): Promise<void>;\n  resolveId(source: string): { id: string; moduleSideEffects: true } | null;\n  load(id: string): string | null;\n  /** The imports to append to module `id` for the features its `code` may use; '' for none. */\n  inject(code: string, id: string, context: ScanContext): Promise<string>;\n}\n\nconst importsOf = (features: readonly Feature[]): string =>\n  features.map((feature) => `\\nimport ${JSON.stringify(PREFIX + feature)};`).join('');\n\n/**\n * Detection for `features`. `ownEntry`: the compiled entry of the core copy running the plugin,\n * used when the app's root can't resolve `@gyral/core/compiled` (fixtures, unusual layouts).\n */\nexport function createFeatures(features: readonly Feature[], ownEntry: string): FeatureHooks {\n  let entry = ownEntry;\n  let scope: Scope = createScope();\n  const skipped = new Set([ownEntry.replace(ENTRY_FILE, '/')]);\n  /** A registration module next to the compiled entry's view/ directory. */\n  const moduleOf = (name: string): string =>\n    entry.replace(ENTRY_FILE, (_, dir: string, ext: string) => `/${dir}/${name}.${ext}`);\n  const isCore = (id: string): boolean => [...skipped].some((dir) => id.startsWith(dir));\n\n  /**\n   * Whether one of `specifiers`, imported by `importer`, is a module of core (where `raw` comes\n   * from): `@gyral/core` or one of its subpaths, or a specifier that resolves into core (an\n   * alias, a path). Another package that re-exports core's `raw` counts in its own module.\n   */\n  async function coreAmong(\n    specifiers: readonly string[],\n    importer: string,\n    resolve: Resolve,\n  ): Promise<boolean> {\n    for (const specifier of specifiers) {\n      if (specifier === CORE || specifier.startsWith(`${CORE}/`)) return true;\n      let resolved: { readonly id: string } | null = null;\n      try {\n        resolved = await resolve(specifier, importer);\n      } catch {\n        // unresolvable: the bundler reports it\n      }\n      const id = resolved?.id.replace(/\\?.*$/, '');\n      if (id !== undefined && (isCore(id) || scope.packageOf(id) === CORE)) return true;\n    }\n    return false;\n  }\n\n  return {\n    async buildStart(resolve, root) {\n      scope = createScope(); // manifests may have changed since the last build (watch mode)\n      const resolved = await resolve('@gyral/core/compiled', join(root, 'index.html'));\n      if (resolved === null || !ENTRY_FILE.test(resolved.id)) return;\n      entry = resolved.id;\n      skipped.add(entry.replace(ENTRY_FILE, '/'));\n    },\n    resolveId(source) {\n      if (!source.startsWith(PREFIX)) return null;\n      const feature = source.slice(PREFIX.length) as Feature;\n      return features.includes(feature)\n        ? { id: RESOLVED + feature, moduleSideEffects: true }\n        : null;\n    },\n    load(id) {\n      if (!id.startsWith(RESOLVED)) return null;\n      const file = moduleOf(REGISTRATION[id.slice(RESOLVED.length) as Feature]);\n      return `import { register } from ${JSON.stringify(file)};\\nregister();\\n`;\n    },\n    async inject(code, id, context) {\n      const file = id.replace(/\\?.*$/, '');\n      if (id.startsWith('\\0') || !SCRIPT.test(file) || isCore(file)) return '';\n      const hinted = features.filter((feature) => FEATURE_HINTS[feature].test(code));\n      if (hinted.length === 0 || !scope.inScope(file)) return '';\n      let program: Node;\n      try {\n        program = context.parse(code, langOf(file)) as Node;\n      } catch {\n        return importsOf(hinted.filter((feature) => TEXT_USES[feature].test(code)));\n      }\n      const facts = factsOf(program);\n      const used: Feature[] = [];\n      for (const feature of hinted) {\n        if (\n          writes(facts, feature) ||\n          (feature === 'invokers' && (await coreAmong(facts.rawSources, id, context.resolve)))\n        )\n          used.push(feature);\n      }\n      return importsOf(used);\n    },\n  };\n}\n"]}

package/dist/compiler/hooks.d.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from 'vite';
+type Fn<H> = H extends {
+    handler: infer F;
+} ? F : H;
+type HookFn<K extends keyof Plugin> = Fn<NonNullable<Plugin[K]>>;
+export interface CompilerHooks {
+    readonly configResolved: HookFn<'configResolved'>;
+    readonly buildStart: HookFn<'buildStart'>;
+    readonly resolveId: HookFn<'resolveId'>;
+    readonly load: HookFn<'load'>;
+    readonly transform: HookFn<'transform'>;
+    readonly generateBundle: HookFn<'generateBundle'>;
+}
+export interface CompilerSettings {
+    readonly sources: readonly string[];
+    /** The module to load parse5 from; undefined skips the parse5 check. */
+    readonly parse5: string | undefined;
+    /** The compiled entry of the core copy running the plugin (features.ts). */
+    readonly ownEntry: string;
+}
+export declare function createCompiler(settings: CompilerSettings): CompilerHooks;
+export {};

package/dist/compiler/hooks.js

@@ -0,0 +1,241 @@
+// The template compiler's build hooks (view/01-templates.md "Compiled",
+// view/09-template-rules.md), loaded lazily by the plugin shell in ../vite.ts on the first
+// `vite build` hook, so the preset stays loadable from any vite.config.ts:
+//   - `transform` (the shell is enforce: 'pre', so positions are the author's own source,
+//     TypeScript included, parsed by Rolldown's `this.parse`): rewrites each `html` call site
+//     of the configured sources into `compiled(<hoisted template object>, [values…])` (and
+//     each `svg` one into `compiledSvg(…)`), dependencies in node_modules included. Template
+//     rule violations, and references it can't follow, fail the build with a code frame.
+//   - `generateBundle`: fails when an uncompiled `html` or `svg` survived in a chunk anyway
+//     (re-exports across modules, dynamic imports): the guarantee that the `#prepare` stub is
+//     never hit.
+//   - In client environments, `transform` also adds the registration of view transitions, the
+//     frame lane and custom states to every module that names their spec field, among the
+//     modules that can affect Gyral components (the app's own, and packages that reach a Gyral
+//     package), so the `gyral-compiled` condition can leave them out otherwise (features.ts,
+//     gyral-c5d.12); `resolveId` and `load` serve those registration modules.
+import { join, relative } from 'node:path';
+import { langOf } from './ast.js';
+import { CompileError, compileModule } from './compile.js';
+import { createFeatures } from './features.js';
+import { stripPropSchemas } from './prop-schemas.js';
+import { loadParse5 } from './parse5-check.js';
+import { VIEW } from './locate.js';
+import { findUses, htmlImports } from './scan.js';
+import { Lines, splice } from './source.js';
+/** Appends `imports` after the module's last line: no code moves, so source maps hold. */
+const appended = (result, code, imports) => imports === ''
+    ? result
+    : result === null
+        ? { code: code + imports, map: null }
+        : { ...result, code: result.code + imports };
+/** Modules naming a template tag, or calling `.value(`: only those can need compiling. */
+const NAMES_TAG = /html|svg|\.value\s*\(/;
+/** A `prop.value(…)` call may be in the module (prop-schemas.ts). */
+const PROP_VALUE = /\.value\s*\(/;
+/** template.ts's symbol description: the module defining `html` and `svg`, in any copy of core. */
+const DEFINES_HTML = /Symbol\(['"]gyral\.template['"]\)/;
+const SCRIPT = /\.[cm]?[jt]sx?$/;
+/**
+ * Whether an environment resolves core's `#view-dev` to its development module: the
+ * `development` condition is listed, or Vite's `development|production` placeholder is and
+ * the build isn't a production one. Exactly then the client keeps template ids (01).
+ */
+function developmentBuild(config) {
+    const { conditions } = config.resolve;
+    return (conditions.includes('development') ||
+        (!config.isProduction && conditions.includes('development|production')));
+}
+const CANT_FOLLOW = `This use of html can't be compiled: the template compiler rewrites only html\`…\` tagged ` +
+    `templates whose tag is the imported html itself (or ns.html for import * as ns; the same ` +
+    `for svg). ` +
+    `Aliasing it, passing it around or calling it as a function would reach the runtime ` +
+    `template preparer, which builds made with the Gyral preset leave out. Write html\`…\` at ` +
+    `the call site (view/01-templates.md "Compiled").`;
+export function createCompiler(settings) {
+    const { sources } = settings;
+    const features = createFeatures([
+        'transitions',
+        'frame',
+        'states',
+        'forms',
+        'subscriptions',
+        'dialogs',
+        'disposal',
+        'errorView',
+        'errored',
+    ], settings.ownEntry);
+    /** Per environment (client, ssr, …): Vite may build them with one plugin instance. */
+    const states = new WeakMap();
+    const global = {};
+    let root = '';
+    let treeshake = true;
+    let info = () => undefined;
+    let parse5;
+    function stateOf(env) {
+        const key = env ?? global;
+        let state = states.get(key);
+        if (state === undefined) {
+            state = { sourceIds: new Set(VIEW), definers: new Set(), seen: new Map() };
+            states.set(key, state);
+        }
+        return state;
+    }
+    /** parse5, loaded once; the notice when it is missing is printed once too. */
+    function loadOnce() {
+        const specifier = settings.parse5;
+        if (specifier === undefined)
+            return undefined;
+        if (parse5 === undefined) {
+            parse5 = { module: loadParse5(specifier, root) };
+            if (parse5.module === undefined) {
+                info(`gyral: ${specifier} is not installed, so the template compiler skips its extra ` +
+                    `rule 7 check (the normalizer's own check still runs). To get it: pnpm add -D ` +
+                    `parse5 (view/09-template-rules.md).`);
+            }
+        }
+        return parse5.module;
+    }
+    /** Compiles the module's template call sites (the transform proper). */
+    async function compile(code, id, opts) {
+        if (id.startsWith('\0') || !SCRIPT.test(id))
+            return null;
+        const env = this.environment;
+        const state = stateOf(env);
+        if (DEFINES_HTML.test(code))
+            state.definers.add(id);
+        if (state.sourceIds.has(id))
+            return null;
+        let program;
+        try {
+            program = this.parse(code, { lang: langOf(id) });
+        }
+        catch {
+            return null; // not ours to report: the bundler fails on it with a better message
+        }
+        const lines = new Lines(code);
+        const file = relative(root, id);
+        // Production client builds: property-only prop checks can't run (prop-schemas.ts).
+        const client = opts?.ssr !== true && env.config.consumer === 'client';
+        const extra = client && !developmentBuild(env.config) && PROP_VALUE.test(code)
+            ? stripPropSchemas(program, code)
+            : [];
+        const unchanged = () => (extra.length === 0 ? null : splice(lines, extra, id));
+        const { imports, reexports } = htmlImports(program);
+        if (imports.length === 0 && reexports.length === 0)
+            return unchanged();
+        const isSource = async (specifier) => {
+            if (sources.includes(specifier))
+                return true;
+            const resolved = await this.resolve(specifier, id);
+            return resolved !== null && state.sourceIds.has(resolved.id);
+        };
+        const where = (node) => `${file}:${String(lines.position(node.start).line)}`;
+        for (const r of reexports) {
+            if (!(await isSource(r.specifier)))
+                continue;
+            this.warn(`${where(r.node)}: re-exporting html or svg. The template compiler only follows the ` +
+                `tags imported straight from ${r.specifier}: templates written with this re-export ` +
+                `stay uncompiled and fail the build. Import them from ${r.specifier} instead.`);
+        }
+        const matched = [];
+        for (const binding of imports)
+            if (await isSource(binding.specifier))
+                matched.push(binding);
+        if (matched.length === 0)
+            return unchanged();
+        const fail = (start, end, message) => this.error({
+            message,
+            id,
+            loc: { file: id, ...lines.position(start) },
+            frame: lines.frame(start, end),
+        });
+        const { sites, leftovers } = findUses(program, matched);
+        for (const l of leftovers) {
+            if (l.exported)
+                this.warn(`${where(l.node)}: re-exporting a template tag; its users stay uncompiled.`);
+            else
+                fail(l.node.start, l.node.end, CANT_FOLLOW);
+        }
+        if (sites.length === 0)
+            return unchanged();
+        const ssr = opts?.ssr === true || env.config.consumer === 'server';
+        try {
+            return compileModule({
+                lines,
+                id,
+                file,
+                sites,
+                ssr,
+                ids: ssr || developmentBuild(env.config),
+                parse5: loadOnce(),
+                extra,
+                seen: state.seen,
+            });
+        }
+        catch (error) {
+            if (error instanceof CompileError)
+                return fail(error.start, error.end, error.message);
+            throw error;
+        }
+    }
+    return {
+        configResolved(config) {
+            root = config.root;
+            treeshake = config.build.rolldownOptions.treeshake !== false;
+            info = (message) => {
+                config.logger.info(message);
+            };
+        },
+        async buildStart() {
+            states.delete(this.environment);
+            const state = stateOf(this.environment);
+            for (const source of sources) {
+                const resolved = await this.resolve(source, join(root, 'index.html'));
+                if (resolved !== null)
+                    state.sourceIds.add(resolved.id);
+            }
+            await features.buildStart((source, importer) => this.resolve(source, importer), root);
+            loadOnce();
+        },
+        resolveId(source) {
+            return features.resolveId(source);
+        },
+        load(id) {
+            return features.load(id);
+        },
+        async transform(code, id, opts) {
+            const client = opts?.ssr !== true && this.environment.config.consumer === 'client';
+            const imports = client
+                ? await features.inject(code, id, {
+                    parse: (text, lang) => this.parse(text, { lang }),
+                    resolve: (source, importer) => this.resolve(source, importer),
+                })
+                : '';
+            const compiled = NAMES_TAG.test(code) ? await compile.call(this, code, id, opts) : null;
+            return appended(compiled, code, imports);
+        },
+        generateBundle(_, bundle) {
+            const state = stateOf(this.environment);
+            // Without tree-shaking every export is rendered, used or not.
+            if (state.definers.size === 0 || !treeshake)
+                return;
+            for (const chunk of Object.values(bundle)) {
+                if (chunk.type !== 'chunk')
+                    continue;
+                for (const [id, module] of Object.entries(chunk.modules)) {
+                    const tag = ['html', 'svg'].find((name) => module.renderedExports.includes(name));
+                    if (!state.definers.has(id) || tag === undefined)
+                        continue;
+                    this.error(`gyral: an uncompiled ${tag} template remains in ${chunk.fileName}: something uses ` +
+                        `${tag} from ${relative(root, id)} in a way the template compiler can't see (a ` +
+                        `re-export, a dynamic import, or a module it doesn't process). With the ` +
+                        `gyral-compiled condition the runtime preparer is left out, so that template ` +
+                        `would throw. Import ${tag} straight from '@gyral/core' where you write templates ` +
+                        `(view/01-templates.md "Compiled").`);
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/compiler/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/compiler/hooks.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,2FAA2F;AAC3F,2EAA2E;AAC3E,0FAA0F;AAC1F,8FAA8F;AAC9F,2FAA2F;AAC3F,6FAA6F;AAC7F,yFAAyF;AACzF,4FAA4F;AAC5F,8FAA8F;AAC9F,iBAAiB;AACjB,8FAA8F;AAC9F,0FAA0F;AAC1F,+FAA+F;AAC/F,6FAA6F;AAC7F,8EAA8E;AAC9E,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,MAAM,EAAa,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAe,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAkB,MAAM,aAAa,CAAC;AA2B5D,0FAA0F;AAC1F,MAAM,QAAQ,GAAG,CAAC,MAAmB,EAAE,IAAY,EAAE,OAAe,EAAe,EAAE,CACnF,OAAO,KAAK,EAAE;IACZ,CAAC,CAAC,MAAM;IACR,CAAC,CAAC,MAAM,KAAK,IAAI;QACf,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE;QACrC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,GAAG,OAAO,EAAE,CAAC;AAEnD,0FAA0F;AAC1F,MAAM,SAAS,GAAG,uBAAuB,CAAC;AAC1C,qEAAqE;AACrE,MAAM,UAAU,GAAG,cAAc,CAAC;AAElC,mGAAmG;AACnG,MAAM,YAAY,GAAG,mCAAmC,CAAC;AACzD,MAAM,MAAM,GAAG,iBAAiB,CAAC;AAQjC;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,MAGzB;IACC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC;IACtC,OAAO,CACL,UAAU,CAAC,QAAQ,CAAC,aAAa,CAAC;QAClC,CAAC,CAAC,MAAM,CAAC,YAAY,IAAI,UAAU,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAAC,CACxE,CAAC;AACJ,CAAC;AAED,MAAM,WAAW,GACf,2FAA2F;IAC3F,2FAA2F;IAC3F,YAAY;IACZ,qFAAqF;IACrF,2FAA2F;IAC3F,kDAAkD,CAAC;AAErD,MAAM,UAAU,cAAc,CAAC,QAA0B;IACvD,MAAM,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC;IAC7B,MAAM,QAAQ,GAAG,cAAc,CAC7B;QACE,aAAa;QACb,OAAO;QACP,QAAQ;QACR,OAAO;QACP,eAAe;QACf,SAAS;QACT,UAAU;QACV,WAAW;QACX,SAAS;KACV,EACD,QAAQ,CAAC,QAAQ,CAClB,CAAC;IACF,sFAAsF;IACtF,MAAM,MAAM,GAAG,IAAI,OAAO,EAAsB,CAAC;IACjD,MAAM,MAAM,GAAG,EAAE,CAAC;IAClB,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,IAAI,GAA8B,GAAG,EAAE,CAAC,SAAS,CAAC;IACtD,IAAI,MAA2D,CAAC;IAEhE,SAAS,OAAO,CAAC,GAAuB;QACtC,MAAM,GAAG,GAAG,GAAG,IAAI,MAAM,CAAC;QAC1B,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,GAAG,EAAE,SAAS,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;YAC3E,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,8EAA8E;IAC9E,SAAS,QAAQ;QACf,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;QAClC,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC9C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC;YACjD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAChC,IAAI,CACF,UAAU,SAAS,8DAA8D;oBAC/E,+EAA+E;oBAC/E,qCAAqC,CACxC,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,wEAAwE;IACxE,KAAK,UAAU,OAAO,CAEpB,IAAY,EACZ,EAAU,EACV,IAAsB;QAEtB,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC;QAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpD,IAAI,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QACzC,IAAI,OAAa,CAAC;QAClB,IAAI,CAAC;YACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAoB,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,CAAC,oEAAoE;QACnF,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAChC,mFAAmF;QACnF,MAAM,MAAM,GAAG,IAAI,EAAE,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC;QACtE,MAAM,KAAK,GACT,MAAM,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAC9D,CAAC,CAAC,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC;YACjC,CAAC,CAAC,EAAE,CAAC;QACT,MAAM,SAAS,GAAG,GAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QAC5F,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,EAAE,CAAC;QACvE,MAAM,QAAQ,GAAG,KAAK,EAAE,SAAiB,EAAoB,EAAE;YAC7D,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC7C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YACnD,OAAO,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC/D,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,CAAC,IAAU,EAAU,EAAE,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3F,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;gBAAE,SAAS;YAC7C,IAAI,CAAC,IAAI,CACP,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,qEAAqE;gBACnF,+BAA+B,CAAC,CAAC,SAAS,0CAA0C;gBACpF,wDAAwD,CAAC,CAAC,SAAS,WAAW,CACjF,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,CAAC;QACnB,KAAK,MAAM,OAAO,IAAI,OAAO;YAAE,IAAI,MAAM,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5F,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,GAAW,EAAE,OAAe,EAAS,EAAE,CAClE,IAAI,CAAC,KAAK,CAAC;YACT,OAAO;YACP,EAAE;YACF,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE;YAC3C,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC;SAC/B,CAAC,CAAC;QACL,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,QAAQ;gBACZ,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;;gBACpF,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC;QACnE,IAAI,CAAC;YACH,OAAO,aAAa,CAAC;gBACnB,KAAK;gBACL,EAAE;gBACF,IAAI;gBACJ,KAAK;gBACL,GAAG;gBACH,GAAG,EAAE,GAAG,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC;gBACxC,MAAM,EAAE,QAAQ,EAAE;gBAClB,KAAK;gBACL,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,YAAY;gBAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YACtF,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO;QACL,cAAc,CAAC,MAAM;YACnB,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;YACnB,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,SAAS,KAAK,KAAK,CAAC;YAC7D,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE;gBACjB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC9B,CAAC,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,UAAU;YACd,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAChC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACxC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;gBACtE,IAAI,QAAQ,KAAK,IAAI;oBAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAC1D,CAAC;YACD,MAAM,QAAQ,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC;YACtF,QAAQ,EAAE,CAAC;QACb,CAAC;QAED,SAAS,CAAC,MAAM;YACd,OAAO,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,CAAC,EAAE;YACL,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3B,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI;YAC5B,MAAM,MAAM,GAAG,IAAI,EAAE,GAAG,KAAK,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC;YACnF,MAAM,OAAO,GAAG,MAAM;gBACpB,CAAC,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE;oBAC9B,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC;oBACjD,OAAO,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC;iBAC9D,CAAC;gBACJ,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACxF,OAAO,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QAED,cAAc,CAAC,CAAC,EAAE,MAAM;YACtB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACxC,8DAA8D;YAC9D,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS;gBAAE,OAAO;YACpD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1C,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;oBAAE,SAAS;gBACrC,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;oBACzD,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;oBAClF,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,KAAK,SAAS;wBAAE,SAAS;oBAC3D,IAAI,CAAC,KAAK,CACR,wBAAwB,GAAG,wBAAwB,KAAK,CAAC,QAAQ,mBAAmB;wBAClF,GAAG,GAAG,SAAS,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,+CAA+C;wBAChF,yEAAyE;wBACzE,8EAA8E;wBAC9E,uBAAuB,GAAG,yDAAyD;wBACnF,oCAAoC,CACvC,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// The template compiler's build hooks (view/01-templates.md \"Compiled\",\n// view/09-template-rules.md), loaded lazily by the plugin shell in ../vite.ts on the first\n// `vite build` hook, so the preset stays loadable from any vite.config.ts:\n//   - `transform` (the shell is enforce: 'pre', so positions are the author's own source,\n//     TypeScript included, parsed by Rolldown's `this.parse`): rewrites each `html` call site\n//     of the configured sources into `compiled(<hoisted template object>, [values…])` (and\n//     each `svg` one into `compiledSvg(…)`), dependencies in node_modules included. Template\n//     rule violations, and references it can't follow, fail the build with a code frame.\n//   - `generateBundle`: fails when an uncompiled `html` or `svg` survived in a chunk anyway\n//     (re-exports across modules, dynamic imports): the guarantee that the `#prepare` stub is\n//     never hit.\n//   - In client environments, `transform` also adds the registration of view transitions, the\n//     frame lane and custom states to every module that names their spec field, among the\n//     modules that can affect Gyral components (the app's own, and packages that reach a Gyral\n//     package), so the `gyral-compiled` condition can leave them out otherwise (features.ts,\n//     gyral-c5d.12); `resolveId` and `load` serve those registration modules.\nimport { join, relative } from 'node:path';\nimport type { Plugin } from 'vite';\nimport { langOf, type Node } from './ast.js';\nimport { CompileError, compileModule } from './compile.js';\nimport { createFeatures } from './features.js';\nimport { stripPropSchemas } from './prop-schemas.js';\nimport { loadParse5, type Parse5 } from './parse5-check.js';\nimport { VIEW } from './locate.js';\nimport { findUses, htmlImports } from './scan.js';\nimport { Lines, splice, type SourceMap } from './source.js';\n\ntype Fn<H> = H extends { handler: infer F } ? F : H;\ntype HookFn<K extends keyof Plugin> = Fn<NonNullable<Plugin[K]>>;\n\nexport interface CompilerHooks {\n  readonly configResolved: HookFn<'configResolved'>;\n  readonly buildStart: HookFn<'buildStart'>;\n  readonly resolveId: HookFn<'resolveId'>;\n  readonly load: HookFn<'load'>;\n  readonly transform: HookFn<'transform'>;\n  readonly generateBundle: HookFn<'generateBundle'>;\n}\n\nexport interface CompilerSettings {\n  readonly sources: readonly string[];\n  /** The module to load parse5 from; undefined skips the parse5 check. */\n  readonly parse5: string | undefined;\n  /** The compiled entry of the core copy running the plugin (features.ts). */\n  readonly ownEntry: string;\n}\n\ntype TransformContext = ThisParameterType<HookFn<'transform'>>;\ntype TransformOptions = Parameters<HookFn<'transform'>>[2];\n/** What `compile` returns: the rewritten module, or null when nothing changed. */\ntype Transformed = { readonly code: string; readonly map: SourceMap | null } | null;\n\n/** Appends `imports` after the module's last line: no code moves, so source maps hold. */\nconst appended = (result: Transformed, code: string, imports: string): Transformed =>\n  imports === ''\n    ? result\n    : result === null\n      ? { code: code + imports, map: null }\n      : { ...result, code: result.code + imports };\n\n/** Modules naming a template tag, or calling `.value(`: only those can need compiling. */\nconst NAMES_TAG = /html|svg|\\.value\\s*\\(/;\n/** A `prop.value(…)` call may be in the module (prop-schemas.ts). */\nconst PROP_VALUE = /\\.value\\s*\\(/;\n\n/** template.ts's symbol description: the module defining `html` and `svg`, in any copy of core. */\nconst DEFINES_HTML = /Symbol\\(['\"]gyral\\.template['\"]\\)/;\nconst SCRIPT = /\\.[cm]?[jt]sx?$/;\n\ninterface BuildState {\n  readonly sourceIds: Set<string>;\n  readonly definers: Set<string>;\n  readonly seen: Map<string, { readonly strings: string; readonly loc: string }>;\n}\n\n/**\n * Whether an environment resolves core's `#view-dev` to its development module: the\n * `development` condition is listed, or Vite's `development|production` placeholder is and\n * the build isn't a production one. Exactly then the client keeps template ids (01).\n */\nfunction developmentBuild(config: {\n  readonly isProduction: boolean;\n  readonly resolve: { readonly conditions: readonly string[] };\n}): boolean {\n  const { conditions } = config.resolve;\n  return (\n    conditions.includes('development') ||\n    (!config.isProduction && conditions.includes('development|production'))\n  );\n}\n\nconst CANT_FOLLOW =\n  `This use of html can't be compiled: the template compiler rewrites only html\\`…\\` tagged ` +\n  `templates whose tag is the imported html itself (or ns.html for import * as ns; the same ` +\n  `for svg). ` +\n  `Aliasing it, passing it around or calling it as a function would reach the runtime ` +\n  `template preparer, which builds made with the Gyral preset leave out. Write html\\`…\\` at ` +\n  `the call site (view/01-templates.md \"Compiled\").`;\n\nexport function createCompiler(settings: CompilerSettings): CompilerHooks {\n  const { sources } = settings;\n  const features = createFeatures(\n    [\n      'transitions',\n      'frame',\n      'states',\n      'forms',\n      'subscriptions',\n      'dialogs',\n      'disposal',\n      'errorView',\n      'errored',\n    ],\n    settings.ownEntry,\n  );\n  /** Per environment (client, ssr, …): Vite may build them with one plugin instance. */\n  const states = new WeakMap<object, BuildState>();\n  const global = {};\n  let root = '';\n  let treeshake = true;\n  let info: (message: string) => void = () => undefined;\n  let parse5: { readonly module: Parse5 | undefined } | undefined;\n\n  function stateOf(env: object | undefined): BuildState {\n    const key = env ?? global;\n    let state = states.get(key);\n    if (state === undefined) {\n      state = { sourceIds: new Set(VIEW), definers: new Set(), seen: new Map() };\n      states.set(key, state);\n    }\n    return state;\n  }\n\n  /** parse5, loaded once; the notice when it is missing is printed once too. */\n  function loadOnce(): Parse5 | undefined {\n    const specifier = settings.parse5;\n    if (specifier === undefined) return undefined;\n    if (parse5 === undefined) {\n      parse5 = { module: loadParse5(specifier, root) };\n      if (parse5.module === undefined) {\n        info(\n          `gyral: ${specifier} is not installed, so the template compiler skips its extra ` +\n            `rule 7 check (the normalizer's own check still runs). To get it: pnpm add -D ` +\n            `parse5 (view/09-template-rules.md).`,\n        );\n      }\n    }\n    return parse5.module;\n  }\n\n  /** Compiles the module's template call sites (the transform proper). */\n  async function compile(\n    this: TransformContext,\n    code: string,\n    id: string,\n    opts: TransformOptions,\n  ): Promise<Transformed> {\n    if (id.startsWith('\\0') || !SCRIPT.test(id)) return null;\n    const env = this.environment;\n    const state = stateOf(env);\n    if (DEFINES_HTML.test(code)) state.definers.add(id);\n    if (state.sourceIds.has(id)) return null;\n    let program: Node;\n    try {\n      program = this.parse(code, { lang: langOf(id) }) as unknown as Node;\n    } catch {\n      return null; // not ours to report: the bundler fails on it with a better message\n    }\n    const lines = new Lines(code);\n    const file = relative(root, id);\n    // Production client builds: property-only prop checks can't run (prop-schemas.ts).\n    const client = opts?.ssr !== true && env.config.consumer === 'client';\n    const extra =\n      client && !developmentBuild(env.config) && PROP_VALUE.test(code)\n        ? stripPropSchemas(program, code)\n        : [];\n    const unchanged = (): Transformed => (extra.length === 0 ? null : splice(lines, extra, id));\n    const { imports, reexports } = htmlImports(program);\n    if (imports.length === 0 && reexports.length === 0) return unchanged();\n    const isSource = async (specifier: string): Promise<boolean> => {\n      if (sources.includes(specifier)) return true;\n      const resolved = await this.resolve(specifier, id);\n      return resolved !== null && state.sourceIds.has(resolved.id);\n    };\n    const where = (node: Node): string => `${file}:${String(lines.position(node.start).line)}`;\n    for (const r of reexports) {\n      if (!(await isSource(r.specifier))) continue;\n      this.warn(\n        `${where(r.node)}: re-exporting html or svg. The template compiler only follows the ` +\n          `tags imported straight from ${r.specifier}: templates written with this re-export ` +\n          `stay uncompiled and fail the build. Import them from ${r.specifier} instead.`,\n      );\n    }\n    const matched = [];\n    for (const binding of imports) if (await isSource(binding.specifier)) matched.push(binding);\n    if (matched.length === 0) return unchanged();\n    const fail = (start: number, end: number, message: string): never =>\n      this.error({\n        message,\n        id,\n        loc: { file: id, ...lines.position(start) },\n        frame: lines.frame(start, end),\n      });\n    const { sites, leftovers } = findUses(program, matched);\n    for (const l of leftovers) {\n      if (l.exported)\n        this.warn(`${where(l.node)}: re-exporting a template tag; its users stay uncompiled.`);\n      else fail(l.node.start, l.node.end, CANT_FOLLOW);\n    }\n    if (sites.length === 0) return unchanged();\n    const ssr = opts?.ssr === true || env.config.consumer === 'server';\n    try {\n      return compileModule({\n        lines,\n        id,\n        file,\n        sites,\n        ssr,\n        ids: ssr || developmentBuild(env.config),\n        parse5: loadOnce(),\n        extra,\n        seen: state.seen,\n      });\n    } catch (error) {\n      if (error instanceof CompileError) return fail(error.start, error.end, error.message);\n      throw error;\n    }\n  }\n\n  return {\n    configResolved(config) {\n      root = config.root;\n      treeshake = config.build.rolldownOptions.treeshake !== false;\n      info = (message) => {\n        config.logger.info(message);\n      };\n    },\n\n    async buildStart() {\n      states.delete(this.environment);\n      const state = stateOf(this.environment);\n      for (const source of sources) {\n        const resolved = await this.resolve(source, join(root, 'index.html'));\n        if (resolved !== null) state.sourceIds.add(resolved.id);\n      }\n      await features.buildStart((source, importer) => this.resolve(source, importer), root);\n      loadOnce();\n    },\n\n    resolveId(source) {\n      return features.resolveId(source);\n    },\n\n    load(id) {\n      return features.load(id);\n    },\n\n    async transform(code, id, opts) {\n      const client = opts?.ssr !== true && this.environment.config.consumer === 'client';\n      const imports = client\n        ? await features.inject(code, id, {\n            parse: (text, lang) => this.parse(text, { lang }),\n            resolve: (source, importer) => this.resolve(source, importer),\n          })\n        : '';\n      const compiled = NAMES_TAG.test(code) ? await compile.call(this, code, id, opts) : null;\n      return appended(compiled, code, imports);\n    },\n\n    generateBundle(_, bundle) {\n      const state = stateOf(this.environment);\n      // Without tree-shaking every export is rendered, used or not.\n      if (state.definers.size === 0 || !treeshake) return;\n      for (const chunk of Object.values(bundle)) {\n        if (chunk.type !== 'chunk') continue;\n        for (const [id, module] of Object.entries(chunk.modules)) {\n          const tag = ['html', 'svg'].find((name) => module.renderedExports.includes(name));\n          if (!state.definers.has(id) || tag === undefined) continue;\n          this.error(\n            `gyral: an uncompiled ${tag} template remains in ${chunk.fileName}: something uses ` +\n              `${tag} from ${relative(root, id)} in a way the template compiler can't see (a ` +\n              `re-export, a dynamic import, or a module it doesn't process). With the ` +\n              `gyral-compiled condition the runtime preparer is left out, so that template ` +\n              `would throw. Import ${tag} straight from '@gyral/core' where you write templates ` +\n              `(view/01-templates.md \"Compiled\").`,\n          );\n        }\n      }\n    },\n  };\n}\n"]}

package/dist/compiler/loader-source.d.ts

@@ -0,0 +1,14 @@
+/** How a production build writes the loader (./components.ts). */
+export interface LoaderOptions {
+    /** Tags the app's entry defines: wait for registration and watch their shadow roots. */
+    readonly known?: readonly string[];
+}
+/**
+ * The loader: imports a tag's module the first time that tag is rendered, in the document or in
+ * the shadow root of a component it defined (now, or after a mutation, checked once per
+ * microtask), then forgets it. It registers itself on `globalThis[Symbol.for('gyral.components')]`
+ * so `componentsReady()` (core) can wait until every rendered tag it knows is defined.
+ * Shadow roots are observed by the one shared MutationObserver; a removed host's root is
+ * dropped from the scan and its registration is collected with it.
+ */
+export declare function loaderSource(tags: ReadonlyMap<string, string>, options?: LoaderOptions): string;

package/dist/compiler/loader-source.js

@@ -0,0 +1,86 @@
+// The component loader's source (./components.ts): a module that imports a tag's module the
+// first time that tag is in the document. No Node imports, so tests can run it in a browser.
+/**
+ * The loader: imports a tag's module the first time that tag is rendered, in the document or in
+ * the shadow root of a component it defined (now, or after a mutation, checked once per
+ * microtask), then forgets it. It registers itself on `globalThis[Symbol.for('gyral.components')]`
+ * so `componentsReady()` (core) can wait until every rendered tag it knows is defined.
+ * Shadow roots are observed by the one shared MutationObserver; a removed host's root is
+ * dropped from the scan and its registration is collected with it.
+ */
+export function loaderSource(tags, options = {}) {
+    const entries = [
+        ...[...tags].map(([tag, url]) => `  [${JSON.stringify(tag)}, () => import(${JSON.stringify(url)})],`),
+        ...(options.known ?? [])
+            .filter((tag) => !tags.has(tag))
+            .map((tag) => `  [${JSON.stringify(tag)}, () => Promise.resolve()],`),
+    ].join('\n');
+    const watched = [...new Set([...tags.keys(), ...(options.known ?? [])])].join(',');
+    return `// Generated by gyralVitePreset({ components: true }).
+const pending = new Map([
+${entries}
+]);
+const known = ${JSON.stringify(watched)};
+const roots = new Set();
+const inflight = new Set();
+let queued = false;
+const observer = new MutationObserver(() => {
+  if (!queued) {
+    queued = true;
+    queueMicrotask(scan);
+  }
+});
+function watch(root) {
+  for (const host of root.querySelectorAll(known)) {
+    const shadow = host.shadowRoot;
+    if (shadow !== null && !roots.has(shadow)) {
+      roots.add(shadow);
+      observer.observe(shadow, { childList: true, subtree: true });
+      watch(shadow);
+    }
+  }
+}
+function scan() {
+  queued = false;
+  for (const root of roots) if (!root.host.isConnected) roots.delete(root);
+  if (known !== '') {
+    watch(document);
+    for (const root of [...roots]) watch(root);
+  }
+  for (const [tag, load] of pending) {
+    if (customElements.get(tag) !== undefined) {
+      pending.delete(tag);
+      continue;
+    }
+    let found = document.querySelector(tag) !== null;
+    for (const root of roots) if (!found && root.querySelector(tag) !== null) found = true;
+    if (!found) continue;
+    pending.delete(tag);
+    const done = load()
+      .then(() => customElements.whenDefined(tag))
+      .then(() => {
+        // The upgraded host renders into its shadow root next: look there too.
+        if (!queued) {
+          queued = true;
+          queueMicrotask(scan);
+        }
+      })
+      .finally(() => inflight.delete(done));
+    inflight.add(done);
+  }
+  if (pending.size === 0) observer.disconnect();
+}
+async function ready() {
+  for (;;) {
+    scan();
+    if (inflight.size === 0) return;
+    await Promise.allSettled([...inflight]);
+    await new Promise((resolve) => setTimeout(resolve));
+  }
+}
+globalThis[Symbol.for('gyral.components')] = { ready };
+observer.observe(document.documentElement, { childList: true, subtree: true });
+scan();
+`;
+}
+//# sourceMappingURL=loader-source.js.map