@fuzdev/fuz_ui 0.191.4 → 0.193.0

package/dist/csp.js

@@ -1,155 +1,175 @@
 /**
- * This is designed for compatibility with SvelteKit
- * and maps to the `KitConfig` `directives` option.
- * The goal is to provide an ergonomic, modern, and safe API
- * for Content Security Policy (CSP) creation
- * that's simple to write and audit, and isn't error-prone.
+ * Builds a CSP directives map for use with SvelteKit's `kit.csp.directives` option.
  *
- * Things like validation and rendering to a string
- * are out of scope and left to SvelteKit.
+ * Restrictive by default; opt into specific permissions via `extend` (append) or
+ * `overrides` (replace). Designed to read as an audit log: every user-added source
+ * is named at exactly one site in the source code. Library defaults are inherited
+ * unless you opt out via `replace_defaults`.
+ *
+ * Validation:
+ * - Unknown directive keys throw.
+ * - Extending a `['none']` directive throws (use `replace_defaults`/`overrides` to opt in).
+ * - `null` for `replace_defaults` (top-level or per-key) throws — omit the option for library
+ *   defaults, pass `{}` to start blank, or use `overrides` to remove a specific directive.
+ * - `null` per-key in `extend` throws (use `overrides` for removal).
+ * - `undefined` per-key is treated as omitted in all three stages.
+ * - Non-object entries in `extend` (`null`, `undefined`, primitives) throw with a friendly error.
+ * - Output is validated to ensure `'none'` never appears alongside other tokens,
+ *   that no directive ends up with an empty array (use `['none']` to forbid all),
+ *   and that every source array contains only strings.
+ *
+ * Things like rendering to a string are out of scope and left to SvelteKit.
  */
-export function create_csp_directives(options = {}) {
-    const { directives: directives_option, trusted_sources, value_defaults_base = csp_directive_value_defaults, value_defaults: value_defaults_option, required_trust_defaults_base = csp_directive_required_trust_defaults, required_trust_defaults: required_trust_defaults_option, } = options;
+export const create_csp_directives = (options = {}) => {
+    const { replace_defaults = csp_directive_value_defaults, extend, overrides } = options;
+    if (replace_defaults === null) {
+        throw new Error(`Invalid value 'null' for options.replace_defaults. ` +
+            `Omit the option to use library defaults, or pass {} to start with no directives.`);
+    }
     const directives = {};
-    // Shallowly merge any provided defaults with the base defaults
-    const value_defaults = { ...value_defaults_base, ...value_defaults_option };
-    // Merge required trust defaults with the base
-    const required_trust_defaults = {
-        ...required_trust_defaults_base,
-        ...required_trust_defaults_option,
+    // `Object.entries` widens to `[string, unknown]` and TS can't re-narrow per-key, so
+    // writes via the validated `directive` need a single trusted-bridge cast — kept inside
+    // this helper so the call sites stay free of type assertions. Clones arrays so callers
+    // don't have to worry about user-supplied arrays leaking into the output.
+    const assign = (directive, value) => {
+        directives[directive] = Array.isArray(value)
+            ? [...value]
+            : value;
     };
-    // Apply defaults from directive specs
-    for (const spec of csp_directive_specs) {
-        const default_value = value_defaults[spec.name];
-        if (default_value == null)
-            continue; // omit null and undefined
-        directives[spec.name] = Array.isArray(default_value)
-            ? [...default_value]
-            : default_value;
-    }
-    // Get trust requirements (with overrides applied)
-    const trust_requirements = new Map();
-    for (const spec of csp_directive_specs) {
-        const required_trust = required_trust_defaults[spec.name];
-        if (required_trust == null)
-            continue; // omit null and undefined
-        trust_requirements.set(spec.name, required_trust);
-    }
-    // Validate trusted_sources directives
-    if (trusted_sources?.length) {
-        for (const spec of trusted_sources) {
-            if (spec.directives) {
-                for (const directive of spec.directives) {
-                    if (parse_csp_directive(directive) === null) {
-                        throw new Error(`Invalid directive in trusted_sources: ${directive}`);
-                    }
+    // Stage 1: starting state from `replace_defaults`.
+    // `{}` starts blank — every directive must come from `extend`/`overrides`.
+    for_each_directive(replace_defaults, 'replace_defaults', (directive, value) => {
+        if (value === null) {
+            throw new Error(`Invalid value 'null' for directive '${directive}' in options.replace_defaults. ` +
+                `Omit the key instead, or use \`overrides: { '${directive}': null }\` to remove.`);
+        }
+        if (value === undefined)
+            return;
+        assign(directive, value);
+    });
+    // Stage 2: append sources per layer in `extend`.
+    if (extend?.length) {
+        for (const layer of extend) {
+            for_each_directive(layer, 'extend', (directive, value) => {
+                // `undefined` is treated as omitted, matching `replace_defaults`/`overrides`.
+                // Lets callers write `{'connect-src': cond ? [API] : undefined}` naturally.
+                if (value === undefined)
+                    return;
+                // `null` is meaningful enough to deserve its own error — users reaching for null
+                // in extend almost always want removal, which lives on `overrides`.
+                if (value === null) {
+                    throw new Error(`Cannot extend directive '${directive}' with null. ` +
+                        `extend can only append sources — to remove a directive from the output, ` +
+                        `use \`overrides: { '${directive}': null }\`.`);
                 }
-            }
+                if (!Array.isArray(value)) {
+                    throw new Error(`Cannot extend directive '${directive}': value must be an array of sources, got ${typeof value}.`);
+                }
+                if (!value.length)
+                    return;
+                const current = directives[directive];
+                if (is_none(current)) {
+                    throw new Error(`Cannot extend directive '${directive}' while its current value is ['none']. ` +
+                        `The pipeline runs replace_defaults → extend → overrides, so an \`overrides\` ` +
+                        `entry for '${directive}' cannot rescue this — extend sees the ['none'] starting ` +
+                        `value first. Opt in via \`replace_defaults: { '${directive}': [...] }\` or move ` +
+                        `the sources into \`overrides: { '${directive}': [...] }\`.`);
+                }
+                if (current === undefined) {
+                    assign(directive, [...new Set(value)]);
+                }
+                else if (Array.isArray(current)) {
+                    assign(directive, [...new Set([...current, ...value])]);
+                }
+                else {
+                    throw new Error(`Cannot extend directive '${directive}': it has a non-array value.`);
+                }
+            });
         }
     }
-    // Apply trusted sources to directives
-    if (trusted_sources?.length) {
-        for (const [key, value] of Object.entries(directives)) {
-            const directive = parse_csp_directive(key);
-            if (directive === null) {
-                throw new Error(`Invalid directive in options.directives: ${key}`);
-            }
-            // Skip if directive is ['none'] or not an array
-            if (is_none_directive(value) || !Array.isArray(value)) {
-                continue;
+    // Stage 3: final-pass `overrides` — replace value or remove key.
+    if (overrides) {
+        for_each_directive(overrides, 'overrides', (directive, value) => {
+            if (value === null) {
+                delete directives[directive]; // eslint-disable-line @typescript-eslint/no-dynamic-delete
             }
-            // Get required trust for this directive
-            const required_trust = trust_requirements.get(directive);
-            if (required_trust == null)
-                continue;
-            // Add matching sources - separate the filtering into trust-based and directive-based inclusion
-            const sources_to_add = trusted_sources
-                .filter((spec) => {
-                // Check for explicit inclusion in directives list
-                const explicitly_included = spec.directives?.includes(directive) ?? false;
-                // Check for trust level based inclusion
-                const has_trust_level = spec.trust !== undefined;
-                const include_by_trust = has_trust_level && is_csp_trusted(required_trust, spec.trust);
-                // Include the source if either condition is met
-                return explicitly_included || include_by_trust;
-            })
-                .map((spec) => spec.source);
-            if (sources_to_add.length > 0) {
-                directives[directive] = [...value, ...sources_to_add];
+            else if (value !== undefined) {
+                assign(directive, value);
             }
-        }
+        });
     }
-    // Apply directive overrides/transformations
-    if (directives_option) {
-        for (const [key, value_or_fn] of Object.entries(directives_option)) {
-            const directive = parse_csp_directive(key);
-            if (directive === null) {
-                throw new Error(`Invalid directive in options.directives: ${key}`);
-            }
-            const current = directives[directive];
-            const result = typeof value_or_fn === 'function' ? value_or_fn(current) : value_or_fn;
-            // Handle `undefined` too just in case
-            if (result == null) {
-                delete directives[directive]; // eslint-disable-line @typescript-eslint/no-dynamic-delete
-            }
-            else {
-                directives[directive] = structuredClone(result);
+    // Stage 4: output validation — empty arrays and mixed `'none'` are invalid CSP.
+    for (const [key, value] of Object.entries(directives)) {
+        if (typeof value === 'boolean')
+            continue;
+        if (!Array.isArray(value)) {
+            throw new Error(`Directive '${key}' has an invalid value: expected an array of sources or a boolean, ` +
+                `got ${value === null ? 'null' : typeof value}.`);
+        }
+        if (value.length === 0) {
+            throw new Error(`Directive '${key}' has an empty array. ` +
+                `Use ['none'] to forbid all sources, or omit the directive entirely.`);
+        }
+        // Element-level type check — the `CspSource` template-string type gates this at the
+        // type layer, but `as any` callers can slip non-strings through. A non-string source
+        // would render as `undefined` / `[object Object]` in the emitted CSP header.
+        for (let i = 0; i < value.length; i++) {
+            const v = value[i];
+            if (typeof v !== 'string') {
+                throw new Error(`Directive '${key}' has a non-string source at index ${i}: got ${v === null ? 'null' : typeof v}.`);
             }
         }
+        if (value.length > 1 && value.includes('none')) {
+            throw new Error(`Directive '${key}' has 'none' alongside other tokens (${value.join(', ')}). ` +
+                `'none' must appear alone in CSP.`);
+        }
     }
     return directives;
-}
+};
 export const parse_csp_directive = (directive) => typeof directive === 'string' && csp_directive_spec_by_name.has(directive)
     ? directive
     : null;
-export const csp_trust_levels = ['low', 'medium', 'high'];
-/**
- * Numeric values for CSP trust levels. See `csp_trust_levels`.
- * Lower is less trusted.
- * Includes `undefined` in the type for safety.
- */
-export const csp_trust_level_value = {
-    low: 0,
-    medium: 1,
-    high: 2,
-};
-/**
- * Validates and extracts a CSP trust level from an unknown value.
- */
-export const parse_csp_trust_level = (trust) => csp_trust_levels.includes(trust) ? trust : null;
+const is_none = (value) => Array.isArray(value) && value.length === 1 && value[0] === 'none';
 /**
- * Determines if a granted trust level is sufficient to satisfy a required trust level.
+ * Iterate over a per-directive options map, validating that every key is a known directive.
+ * Throws if any key fails to parse as a `CspDirective`, mentioning `source_label` so the
+ * error pinpoints which option (`replace_defaults`, `extend`, or `overrides`) was bad.
  *
- * Trust levels have the following hierarchy:
- * - 'high' sources can be used in high, medium, and low trust directives (highest privilege)
- * - 'medium' sources can be used in medium and low trust directives
- * - 'low' sources can only be used in low trust directives (lowest privilege)
+ * Also guards against non-object `source` values (e.g. `extend: [undefined]`, `extend: ['oops']`)
+ * so callers get a friendly library error instead of a cryptic native `TypeError` from
+ * `Object.entries`.
  */
-export const is_csp_trusted = (required_trust, granted_trust) => {
-    const required_value = required_trust && csp_trust_level_value[required_trust];
-    const granted_value = granted_trust && csp_trust_level_value[granted_trust];
-    if (required_value == null || granted_value == null) {
-        return false;
+const for_each_directive = (source, source_label, fn) => {
+    if (source === null || typeof source !== 'object') {
+        const got = source === null ? 'null' : typeof source;
+        throw new Error(`Invalid entry in options.${source_label}: expected an object, got ${got}.`);
+    }
+    for (const [key, value] of Object.entries(source)) {
+        const directive = parse_csp_directive(key);
+        if (directive === null) {
+            throw new Error(`Invalid directive in options.${source_label}: ${key}`);
+        }
+        fn(directive, value);
     }
-    // A source with higher trust privilege (higher value)
-    // can be used in a directive with less privilege (lower value).
-    return granted_value >= required_value;
 };
-/**
- * Helper to check if a directive value is `['none']`,
- * or more precisely for robustness with malformed values, checks for an array with `'none'`.
- */
-const is_none_directive = (value) => Array.isArray(value) && value.includes('none');
 export const COLOR_SCHEME_SCRIPT_HASH = 'sha256-QOxqn7EUzb3ydF9SALJoJGWSvywW9R0AfTDSenB83Z8=';
 /**
- * The base CSP directive defaults.
+ * The library CSP directive defaults — directives enabled out of the box.
  * Prioritizes safety but loosens around media and styles, relying on defense-in-depth.
- * Customizable via `CreateCspDirectivesOptions`.
+ * WASM compile is allowed (`'wasm-unsafe-eval'` on `script-src` and `worker-src`); `eval` is not.
+ *
+ * Directives not listed here (`report-to`, `require-trusted-types-for`, `trusted-types`,
+ * `sandbox`) are intentionally absent by default — opt in via `replace_defaults` or `overrides`.
+ *
+ * Customizable via `CreateCspDirectivesOptions.replace_defaults`.
  */
 export const csp_directive_value_defaults = {
     'default-src': ['none'],
-    'script-src': ['self', COLOR_SCHEME_SCRIPT_HASH], // Eval is opt-in, scripting is locked down except for self and the color scheme loader script
-    'script-src-elem': ['self', COLOR_SCHEME_SCRIPT_HASH], // Block script elements except for self and the color scheme loader
+    // `'wasm-unsafe-eval'` permits WASM compile/instantiate only — `eval` and `new Function`
+    // remain blocked. Needed for `@fuzdev/fuz_util/hash_blake3` and any other WASM in the page.
+    // Pre-2022 browsers ignore the keyword and block WASM; if you need them, override with `'unsafe-eval'`.
+    'script-src': ['self', 'wasm-unsafe-eval', COLOR_SCHEME_SCRIPT_HASH],
+    'script-src-elem': ['self', COLOR_SCHEME_SCRIPT_HASH], // Block script elements except for self and the color scheme loader (WASM compile is gated by script-src, not script-src-elem)
     'script-src-attr': ['none'], // Block scripts in HTML attributes
     'style-src': ['self', 'unsafe-inline'], // Main style directive (uses unsafe-inline but network connections are disallowed by other directives)
     'style-src-elem': ['self', 'unsafe-inline'], // Style elements (standalone stylesheets)
@@ -163,55 +183,17 @@ export const csp_directive_value_defaults = {
     'frame-src': ['self'], // Frames/iframes
     'frame-ancestors': ['self'], // Control what can embed this page
     'form-action': ['self'], // Form submission targets
-    'worker-src': ['self', 'blob:'], // Web workers
+    // `'wasm-unsafe-eval'` mirrors the script-src allowance so WASM compiled inside a Web Worker also works.
+    'worker-src': ['self', 'blob:', 'wasm-unsafe-eval'], // Web workers
     'object-src': ['none'], // Block plugins (Flash, Java, etc.)
     'base-uri': ['none'], // Prevent base tag hijacking
     'upgrade-insecure-requests': true, // Upgrade http to https
-    'report-to': null, // Report violations (e.g. `'/csp-violation-report'`)
-    'require-trusted-types-for': null,
-    'trusted-types': null,
-    sandbox: null,
-};
-/**
- * Sources that meet this trust requirement are included for it by default.
- * If null, no trusted sources are added to the directive automatically.
- * Directives that don't support sources or default to `['none']` are null.
- *
- * Feedback is welcome, please see the issues - https://github.com/fuzdev/fuz_ui/issues
- */
-export const csp_directive_required_trust_defaults = {
-    'default-src': null,
-    'script-src': 'high',
-    'script-src-elem': 'high',
-    'script-src-attr': null,
-    'style-src': 'medium',
-    'style-src-elem': 'medium',
-    'style-src-attr': 'medium',
-    'img-src': 'low',
-    'media-src': 'low',
-    'font-src': 'low',
-    'manifest-src': null,
-    'child-src': null,
-    'connect-src': 'medium',
-    'frame-src': 'medium',
-    'frame-ancestors': 'medium',
-    'form-action': 'medium',
-    'worker-src': 'medium',
-    'object-src': null,
-    'base-uri': null,
-    'upgrade-insecure-requests': null,
-    'report-to': null,
-    'require-trusted-types-for': null,
-    'trusted-types': null,
-    sandbox: null,
 };
 /**
  * Static data descriptors for the CSP directives.
  * Fuz excludes deprecated directives, so those are intentionally omitted,
  * but any newer missing directives are bugs.
  *
- * Could be co-located but is currently here to keep that module smaller.
- *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy}
  */
 export const csp_directive_specs = [

package/dist/csp_of_fuzdev.d.ts

@@ -1,6 +1,16 @@
-import type { CspSourceSpec } from './csp.ts';
+import type { CspDirectives } from './csp.ts';
 /**
- * Trusted sources owned by fuz.dev.
+ * Per-directive sources that allow full interop between fuzdev/sister sites
+ * (`*.fuz.dev`, `*.zzz.software`) — loading assets and APIs from each other,
+ * and iframing in both directions.
+ *
+ * Pass into `create_csp_directives({extend: [csp_directives_of_fuzdev]})`.
+ * Intended for sites within the ecosystem; external apps usually want a
+ * narrower, hand-written allow-list.
+ *
+ * Deliberately scoped — `script-src`, `style-src`, `worker-src`, etc. are not
+ * granted, even between sister sites. Add at the call site if a specific page
+ * needs them.
  */
-export declare const csp_trusted_sources_of_fuzdev: Array<CspSourceSpec>;
+export declare const csp_directives_of_fuzdev: Partial<CspDirectives>;
 //# sourceMappingURL=csp_of_fuzdev.d.ts.map

package/dist/csp_of_fuzdev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csp_of_fuzdev.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/csp_of_fuzdev.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,6BAA6B,EAAE,KAAK,CAAC,aAAa,CAK9D,CAAC"}
+{"version":3,"file":"csp_of_fuzdev.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/csp_of_fuzdev.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,EAAE,OAAO,CAAC,aAAa,CAW3D,CAAC"}

package/dist/csp_of_fuzdev.js

@@ -1,9 +1,25 @@
 /**
- * Trusted sources owned by fuz.dev.
+ * Per-directive sources that allow full interop between fuzdev/sister sites
+ * (`*.fuz.dev`, `*.zzz.software`) — loading assets and APIs from each other,
+ * and iframing in both directions.
+ *
+ * Pass into `create_csp_directives({extend: [csp_directives_of_fuzdev]})`.
+ * Intended for sites within the ecosystem; external apps usually want a
+ * narrower, hand-written allow-list.
+ *
+ * Deliberately scoped — `script-src`, `style-src`, `worker-src`, etc. are not
+ * granted, even between sister sites. Add at the call site if a specific page
+ * needs them.
  */
-export const csp_trusted_sources_of_fuzdev = [
-    { source: 'https://*.fuz.dev/', trust: 'low' },
-    { source: 'https://*.zzz.software/', trust: 'low' },
-    // if needed
-    // {source: 'https://fuzdev.github.io/', trust: 'low'},
-];
+export const csp_directives_of_fuzdev = {
+    'img-src': ['https://*.fuz.dev/', 'https://*.zzz.software/'],
+    'media-src': ['https://*.fuz.dev/', 'https://*.zzz.software/'],
+    'font-src': ['https://*.fuz.dev/', 'https://*.zzz.software/'],
+    'connect-src': ['https://*.fuz.dev/', 'https://*.zzz.software/'],
+    'frame-src': ['https://*.fuz.dev/', 'https://*.zzz.software/'],
+    'frame-ancestors': ['https://*.fuz.dev/', 'https://*.zzz.software/'],
+    // `child-src` is intentionally omitted — it defaults to `['none']`, and `extend` cannot
+    // append to a `'none'`-valued directive. Including it here would break the common
+    // `create_csp_directives({extend: [csp_directives_of_fuzdev]})` call. `frame-src` is its
+    // fallback target anyway, so direct opt-in via `frame-src` is the supported path.
+};

package/dist/dimensions.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dimensions.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/dimensions.svelte.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAU;IACtB,KAAK,EAAE,MAAM,CAAa;IAC1B,MAAM,EAAE,MAAM,CAAa;CAC3B"}
+{"version":3,"file":"dimensions.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/dimensions.svelte.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAU;IACtB,KAAK,EAAE,MAAM,CAAiB;IAC9B,MAAM,EAAE,MAAM,CAAiB;CAC/B"}

package/dist/dimensions.svelte.js

@@ -1,4 +1,4 @@
 export class Dimensions {
-    width = $state(0);
-    height = $state(0);
+    width = $state.raw(0);
+    height = $state.raw(0);
 }

package/dist/library.svelte.d.ts

@@ -25,7 +25,7 @@ export declare class Library {
     readonly package_json: {
         [x: string]: unknown;
         name: string;
-        version: string;
+        version?: string | undefined;
         private?: boolean | undefined;
         description?: string | undefined;
         tagline?: string | undefined;

package/dist/library_generate.js

@@ -81,7 +81,7 @@ export const library_generate = (input) => {
     // Phase 1: Analyze all modules and collect re-exports
     const source_json = {
         name: package_json.name,
-        version: package_json.version,
+        version: package_json.version || '',
         modules,
     };
     // Collect re-exports for phase 2 merging

package/dist/style_variable_helpers.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"style_variable_helpers.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/style_variable_helpers.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAK/D,qBAAa,qBAAqB;IACjC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAa;gBAE5B,OAAO,GAAE,aAAa,GAAG,IAAW;CAGhD;AAED,eAAO,MAAM,yBAAyB;;;CAAwD,CAAC"}
+{"version":3,"file":"style_variable_helpers.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/style_variable_helpers.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAK/D,qBAAa,qBAAqB;IACjC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAiB;gBAEhC,OAAO,GAAE,aAAa,GAAG,IAAW;CAGhD;AAED,eAAO,MAAM,yBAAyB;;;CAAwD,CAAC"}

package/dist/style_variable_helpers.svelte.js

@@ -1,7 +1,7 @@
 import { create_context } from './context_helpers.js';
 // TODO maybe change this to a generic wrapper class for any value?
 export class SelectedStyleVariable {
-    value = $state();
+    value = $state.raw();
     constructor(initial = null) {
         this.value = initial;
     }

package/dist/theme_state.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme_state.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/theme_state.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,KAAK,EAAC,MAAM,0BAA0B,CAAC;AAOrF,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAExD,qBAAa,UAAU;IACtB,KAAK,EAAE,KAAK,CAAa;IACzB,YAAY,EAAE,WAAW,CAAa;gBAE1B,OAAO,CAAC,EAAE,iBAAiB;IAUvC,MAAM,IAAI,cAAc;CAMxB;AACD,eAAO,MAAM,mBAAmB;2CAAwB,UAAU;4BAAV,UAAU;uBAAV,UAAU,WAAV,UAAU;CAAG,CAAC;AAEtE,eAAO,MAAM,iBAAiB,GAAI,cAAc,WAAW,GAAG,IAAI,KAAG,IAOpE,CAAC;AAEF,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,eAAO,MAAM,iBAAiB,GAC7B,cAAc,WAAW,GAAG,IAAI,EAChC,YAA8B,KAC5B,IAEF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC7B,WAAU,WAAoB,EAC9B,YAA8B,KAC5B,WAA4E,CAAC;AAEhF,eAAO,MAAM,UAAU,GAAI,OAAO,KAAK,GAAG,IAAI,EAAE,YAAuB,KAAG,IAEzE,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,WAAU,KAA0B,EAAE,YAAuB,KAAG,KAC3C,CAAC"}
+{"version":3,"file":"theme_state.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/theme_state.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,KAAK,EAAC,MAAM,0BAA0B,CAAC;AAOrF,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAExD,qBAAa,UAAU;IACtB,KAAK,EAAE,KAAK,CAAiB;IAC7B,YAAY,EAAE,WAAW,CAAiB;gBAE9B,OAAO,CAAC,EAAE,iBAAiB;IAUvC,MAAM,IAAI,cAAc;CAMxB;AACD,eAAO,MAAM,mBAAmB;2CAAwB,UAAU;4BAAV,UAAU;uBAAV,UAAU,WAAV,UAAU;CAAG,CAAC;AAEtE,eAAO,MAAM,iBAAiB,GAAI,cAAc,WAAW,GAAG,IAAI,KAAG,IAOpE,CAAC;AAEF,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,eAAO,MAAM,iBAAiB,GAC7B,cAAc,WAAW,GAAG,IAAI,EAChC,YAA8B,KAC5B,IAEF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC7B,WAAU,WAAoB,EAC9B,YAA8B,KAC5B,WAA4E,CAAC;AAEhF,eAAO,MAAM,UAAU,GAAI,OAAO,KAAK,GAAG,IAAI,EAAE,YAAuB,KAAG,IAEzE,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,WAAU,KAA0B,EAAE,YAAuB,KAAG,KAC3C,CAAC"}

package/dist/theme_state.svelte.js

@@ -4,8 +4,8 @@ import { BROWSER } from 'esm-env';
 import { create_context } from './context_helpers.js';
 import { load_from_storage, save_to_storage } from './storage.js';
 export class ThemeState {
-    theme = $state();
-    color_scheme = $state();
+    theme = $state.raw();
+    color_scheme = $state.raw();
     constructor(options) {
         const theme = options?.theme ?? default_themes[0];
         const color_scheme = options?.color_scheme ?? 'auto';

package/dist/tome.d.ts

@@ -1,7 +1,8 @@
 import type { Component } from 'svelte';
 import { z } from 'zod';
 export declare const Tome: z.ZodObject<{
-    name: z.ZodString;
+    slug: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
     category: z.ZodString;
     Component: z.ZodCustom<Component<any, any, string>, Component<any, any, string>>;
     related_tomes: z.ZodArray<z.ZodString>;
@@ -12,13 +13,17 @@ export type Tome = z.infer<typeof Tome>;
 /**
  * @param hash - URL fragment to append, with or without the `#`
  */
-export declare const to_tome_pathname: (item: Tome | string, docs_path?: string, hash?: string) => string;
+export declare const tome_to_pathname: (item: Tome | string, docs_path?: string, hash?: string) => string;
+/**
+ * The display label for a tome — its `title` if set, else its `slug`.
+ */
+export declare const tome_to_title: (tome: Tome) => string;
 export declare const tomes_context: {
     get: (error_message?: string) => () => Map<string, Tome>;
     get_maybe: () => (() => Map<string, Tome>) | undefined;
     set: (value: () => Map<string, Tome>) => () => Map<string, Tome>;
 };
-export declare const get_tome_by_name: (name: string) => Tome;
+export declare const tome_get_by_slug: (slug: string) => Tome;
 export declare const tome_context: {
     get: (error_message?: string) => () => Tome;
     get_maybe: () => (() => Tome) | undefined;

package/dist/tome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tome.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tome.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAMtB,eAAO,MAAM,IAAI;;;;;;;iBAQf,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC5B,MAAM,IAAI,GAAG,MAAM,EACnB,kBAA6B,EAC7B,OAAO,MAAM,KACX,MAIF,CAAC;AAEF,eAAO,MAAM,aAAa;2CAAwB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;4BAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;uBAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,WAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;CAAG,CAAC;AAEvE,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,IAK/C,CAAC;AAEF,eAAO,MAAM,YAAY;2CAAwB,IAAI;4BAAJ,IAAI;uBAAJ,IAAI,WAAJ,IAAI;CAAG,CAAC"}
+{"version":3,"file":"tome.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tome.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAMtB,eAAO,MAAM,IAAI;;;;;;;;iBAoBf,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC5B,MAAM,IAAI,GAAG,MAAM,EACnB,kBAA6B,EAC7B,OAAO,MAAM,KACX,MAIF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,IAAI,KAAG,MAAiC,CAAC;AAE7E,eAAO,MAAM,aAAa;2CAAwB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;4BAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;uBAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,WAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;CAAG,CAAC;AAEvE,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,IAK/C,CAAC;AAEF,eAAO,MAAM,YAAY;2CAAwB,IAAI;4BAAJ,IAAI;uBAAJ,IAAI,WAAJ,IAAI;CAAG,CAAC"}

package/dist/tome.js

@@ -2,9 +2,21 @@ import { resolve } from '$app/paths';
 import { z } from 'zod';
 import { ensure_start } from '@fuzdev/fuz_util/string.js';
 import { create_context } from './context_helpers.js';
-import { DOCS_PATH_DEFAULT, docs_slugify } from './docs_helpers.svelte.js';
+import { DOCS_PATH_DEFAULT } from './docs_helpers.svelte.js';
 export const Tome = z.object({
-    name: z.string(),
+    /**
+     * Stable identifier and URL path segment — must be a URL-safe slug
+     * (used directly as the route segment, the lookup key, and in
+     * `related_tomes` cross-references). Set `title` for the display label.
+     */
+    slug: z.string(),
+    /**
+     * Human-readable display label shown in menus, headings, and links.
+     * Falls back to `slug` when omitted, so set `title` to give multi-word or
+     * specially cased tomes a readable label (e.g. `slug: 'vite-plugin'` →
+     * `title: 'vite plugin'`).
+     */
+    title: z.string().optional(),
     // TODO maybe now this makes sense with mdz? summary: z.string(),
     category: z.string(),
     Component: z.custom(),
@@ -15,17 +27,21 @@ export const Tome = z.object({
 /**
  * @param hash - URL fragment to append, with or without the `#`
  */
-export const to_tome_pathname = (item, docs_path = DOCS_PATH_DEFAULT, hash) => {
-    const name = typeof item === 'string' ? item : item.name;
-    const path = docs_path + '/' + docs_slugify(name);
+export const tome_to_pathname = (item, docs_path = DOCS_PATH_DEFAULT, hash) => {
+    const slug = typeof item === 'string' ? item : item.slug;
+    const path = docs_path + '/' + slug;
     return resolve((hash ? path + ensure_start(hash, '#') : path));
 };
+/**
+ * The display label for a tome — its `title` if set, else its `slug`.
+ */
+export const tome_to_title = (tome) => tome.title ?? tome.slug;
 export const tomes_context = create_context();
-export const get_tome_by_name = (name) => {
+export const tome_get_by_slug = (slug) => {
     const get_tomes = tomes_context.get();
-    const tome = get_tomes().get(name);
+    const tome = get_tomes().get(slug);
     if (!tome)
-        throw Error(`unable to find tome "${name}"`);
+        throw Error(`unable to find tome "${slug}"`);
     return tome;
 };
 export const tome_context = create_context();

package/dist/tsdoc_helpers.d.ts

@@ -98,6 +98,15 @@ export declare const tsdoc_parse: (node: ts.Node, source_file: ts.SourceFile) =>
  * @mutates declaration - adds doc_comment, deprecated_message, examples, see_also, throws, since fields
  */
 export declare const tsdoc_apply_to_declaration: (declaration: DeclarationJson, tsdoc: TsdocParsedComment | undefined) => void;
+/**
+ * Concatenates a JSDoc comment (string or node array) into plain text, preserving `{@link ...}`.
+ *
+ * `JSDocLink` / `JSDocLinkCode` / `JSDocLinkPlain` nodes have empty `.text` — the identifier
+ * lives on `.name`, not `.text`. Using `.text` alone silently drops link content; we fall back
+ * to the source-text representation for link nodes so `{@link Foo}` survives intact for downstream
+ * renderers (see `tsdoc_mdz.ts`).
+ */
+export declare const tsdoc_comment_to_text: (comment: string | ts.NodeArray<ts.JSDocComment>, source_file: ts.SourceFile) => string;
 /**
  * Clean raw JSDoc comment text by removing comment markers and leading asterisks.
  *

package/dist/tsdoc_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tsdoc_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACrD,oCAAoC;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GACvB,MAAM,EAAE,CAAC,IAAI,EACb,aAAa,EAAE,CAAC,UAAU,KACxB,kBAAkB,GAAG,SAyFvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,eAAe,EAC5B,OAAO,kBAAkB,GAAG,SAAS,KACnC,IAmBF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,MAAM,GAAG,SAUnE,CAAC"}
+{"version":3,"file":"tsdoc_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACrD,oCAAoC;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GACvB,MAAM,EAAE,CAAC,IAAI,EACb,aAAa,EAAE,CAAC,UAAU,KACxB,kBAAkB,GAAG,SAoFvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,eAAe,EAC5B,OAAO,kBAAkB,GAAG,SAAS,KACnC,IAmBF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,MAAM,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,YAAY,CAAC,EAC/C,aAAa,EAAE,CAAC,UAAU,KACxB,MAGF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,MAAM,GAAG,SAUnE,CAAC"}