@texuli/core 0.0.0-stage → 0.1.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dailybot, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# @texuli/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Layer L0: texels.** Framework-free TypeScript behavior and policy that every
+Texuli component is built from. No Svelte, no runtime dependencies. Private
+workspace package (`"private": true`), not published.
+
+## What exists today
+
+Every texel in the table below is implemented, tested and documented in this
+package. The public API is exactly what the root barrel `src/index.ts`
+exports; each texel is also a per-area subpath export in `package.json`
+(`@texuli/core/<area>`), so consumers can import narrowly and tree-shake the
+rest.
+
+| Texel | Headline exports | Doc |
+| --- | --- | --- |
+| Announcer | `createAnnouncer`, `createLiveRegion`, `getAnnouncer`, `appendRegion` | [core-announcer](docs/core-announcer.md) |
+| Controllable state | `createControllableState` | [core-controllable](docs/core-controllable.md) |
+| Direction and locale | `directionOf`, `inlineSideToPhysical`, `createCollator`, `compareLocale`, `resolveMessages` | [core-dir-locale](docs/core-dir-locale.md) |
+| Dismiss | `bindDismissLayer`, `isPointerOutside`, `isFocusOutside`, `createDismissOutsideEvent`, `createOpenGestureGuard` | [core-dismiss](docs/core-dismiss.md) |
+| Environment | `isBrowser`, `getOwnerDocument`, `getOwnerWindow`, `listen`, `matchesMedia`, `requestFrame` | [core-env](docs/core-env.md) |
+| Focus scope | `createFocusScope` | [core-focus-scope](docs/core-focus-scope.md) |
+| Form bridge | `createFormBridge` | [core-form-bridge](docs/core-form-bridge.md) |
+| Ids | `createIdScope`, `createIdFamily`, `joinIds`, `ariaLabelledBy`, `ariaDescribedBy`, `ariaControls`, `ensureElementId`, `sanitizeIdPart` | [core-ids](docs/core-ids.md) |
+| Inert | `createInertRegistry`, `getInertRegistry`, `computeInertTargets` | [core-inert](docs/core-inert.md) |
+| Keyboard | `parseShortcut`, `matchesShortcut`, `formatShortcut`, `createShortcutMap`, `getNavigationIntent`, `normalizeKey`, `detectPlatform` | [core-keyboard](docs/core-keyboard.md) |
+| Layer stack | `createLayerStack`, `getLayerStack`, `decideEscape`, `bindLayerStackDocument`, `layerReceivesEscape` | [core-layer-stack](docs/core-layer-stack.md) |
+| Lazy chunks | `lazyChunk`, `hasLazyChunk`, `clearLazyChunk(s)` (subpath `@texuli/core/lazy`; not in the root barrel) | — |
+| Overlay engine | `createOverlay` (`OVERLAY_MODE_ATTR`, `OVERLAY_Z_BASE`); the reduced surface is the `@texuli/core/overlay-core` subpath | [core-overlay-core](docs/core-overlay-core.md), [overlay-engine](docs/overlay-engine.md) |
+| Portal | `createPortal` | [core-portal](docs/core-portal.md) |
+| Positioning (DOM) | `positionFloating`, `applyPosition`, `autoUpdate`, `observeMove`, `cssAnchorDeclarations`, `supportsCssAnchorPositioning` | [core-position-dom](docs/core-position-dom.md) |
+| Positioning (math) | `computePosition`, `place`, `shiftIntoBoundary`, `sizeToAvailable`, `listPlacements`, `resolvePlacementForDirection`, `rect` | [core-position-math](docs/core-position-math.md) |
+| Presence | `createPresence`, `prefersReducedMotion`, `hasPendingMotion`, `parseCssTimeList` | [core-presence](docs/core-presence.md) |
+| Roving focus + typeahead | `createRovingFocus`, `createTypeahead`, `stepRovingIndex`, `setRovingTabIndex`, `indexOfSelected` | [core-roving](docs/core-roving.md) |
+| Scroll lock | `lockScroll` | [core-scroll-lock](docs/core-scroll-lock.md) |
+| Tabbable | `isFocusable`, `isTabbable`, `getFocusableElements`, `getTabbableElements` | [core-tabbable](docs/core-tabbable.md) |
+| URL policy (links) | `safeHref`, `type HrefTrust` | [core-url-policy](docs/core-url-policy.md) |
+| URL policy (media) | `safeImageSrc`, `safeImageSrcset`, `safeMediaSrc`, `MAX_DATA_IMAGE_BYTES` | [core-url-policy](docs/core-url-policy.md) |
+
+The tables above name the headline exports per texel, not the full surface:
+read `src/index.ts` (and the per-area `index.ts`) for every exported symbol
+and type. The threat model behind the URL policy lives in
+[docs/SECURITY.md](../../docs/SECURITY.md).
+
+## Examples
+
+```ts
+import {
+  safeHref,
+  createIdScope,
+  ariaLabelledBy,
+  getLayerStack,
+  decideEscape,
+  getTabbableElements,
+  isTabbable,
+} from '@texuli/core';
+
+safeHref('https://example.com/a');            // 'https://example.com/a'
+safeHref('http://example.com');               // undefined (untrusted is the default)
+safeHref('/docs/button', 'developer');        // '/docs/button'
+safeHref('javascript:alert(1)', 'developer'); // undefined in every tier
+
+const ids = createIdScope({ prefix: 'dialog' });
+const titleId = ids.next('title');            // scoped, SSR-stable
+ariaLabelledBy(titleId);                      // the id list for aria-labelledby
+
+const stack = getLayerStack();
+const layer = stack.register({ element: panelEl, label: 'dialog' });
+decideEscape(stack, { key: 'Escape' }); // reaches only the topmost layer
+layer.unregister();
+
+const stops = getTabbableElements(dialogElement);
+isTabbable(stops[0]!);                        // true
+```
+
+### URL policy tiers
+
+- **`untrusted`** (default, for agent or user content): only `https:`,
+  `mailto:` and `#fragment`.
+- **`developer`** (for app-authored props): anything except `javascript:`,
+  `vbscript:`, `data:` and protocol-relative `//host` URLs.
+- Whitespace and ASCII control characters are stripped before the scheme is
+  read, so `java\tscript:` is caught.
+
+Images and media use the element-specific policies: `safeImageSrc` allows
+HTTPS and relative assets from either tier, plus (developer tier only) HTTP,
+valid blob URLs, and PNG, JPEG, GIF, WebP or AVIF base64 data images up to
+1 MiB decoded; SVG and non-image data URLs are always refused.
+`safeImageSrcset` accepts a comma-separated `srcset` only when every candidate
+is safe. `safeMediaSrc` restricts untrusted audio/video to blob URLs or exact
+origins from an HTTPS `allowedOrigins` list. Full contract:
+[core-url-policy](docs/core-url-policy.md).
+
+## Layout
+
+```text
+packages/core/
+├── package.json     exports "." and one subpath per texel; script: typecheck
+├── tsconfig.json    extends ../../tsconfig.base.json
+├── docs/            one contract doc per texel (core-*.md) + overlay-engine.md
+├── src/index.ts     the public barrel (only what is exported here is public)
+├── src/<area>/      one directory per texel (announcer, roving, layer-stack, …)
+└── tests/           22 test files, one or more per texel, including hostile
+                     inputs for every policy that guards a sink
+```
+
+## Rules
+
+- Framework-free: no Svelte or other UI framework imports; standard DOM types
+  are fine.
+- No runtime dependencies; no imports from any other workspace package (L0 is
+  the bottom layer).
+- Policy functions fail closed and document their contract in JSDoc.
+- Every export ships with tests in `tests/<name>.test.ts`, including hostile
+  inputs for anything that guards a sink.
+- Ids never use `Math.random` at module scope; scopes are per-root.
+
+## Testing
+
+```bash
+pnpm vitest run packages/core                    # every core texel test
+pnpm vitest run packages/core/tests/roving.test.ts   # one texel
+pnpm --filter @texuli/core typecheck             # tsc -p tsconfig.json
+npx biome check packages/core                    # lint + format
+```
+
+Core is shared by every layer above it, so a change here also runs
+`pnpm check`, the primitives behavior suite and `pnpm build`
+([TESTING_GUIDE](../../docs/TESTING_GUIDE.md)).
+To add a texel, follow
+[`.agents/skills/add-texel/SKILL.md`](../../.agents/skills/add-texel/SKILL.md).

package/dist/announcer/announcer.d.ts

@@ -0,0 +1,24 @@
+import type { Announcer, CreateAnnouncerOptions } from './types.js';
+import { ANNOUNCER_GLOBAL_KEY } from './types.js';
+/**
+ * Create a live-region announcer bound to one document.
+ *
+ * Owns one polite (`role="status"`) and one assertive (`role="alert"`) region.
+ * Announcements are debounced per region, deduplicated, written with
+ * `textContent` only, and the region nodes are registered as inert exemptions
+ * so they keep working under modals.
+ */
+export declare function createAnnouncer(options: CreateAnnouncerOptions): Announcer;
+export type AnnouncerGlobal = {
+    [ANNOUNCER_GLOBAL_KEY]?: WeakMap<Document, Announcer>;
+};
+/**
+ * Page-wide announcer for `documentRef`, stored on `globalObject` (default
+ * `globalThis`). Separate documents get separate instances.
+ */
+export declare function getAnnouncer(documentRef: Document, options?: Omit<CreateAnnouncerOptions, 'document'>, globalObject?: AnnouncerGlobal): Announcer;
+/**
+ * Drop the shared announcer for `documentRef` (tests). Destroys the instance
+ * when one was stored.
+ */
+export declare function resetAnnouncer(documentRef?: Document, globalObject?: AnnouncerGlobal): void;

package/dist/announcer/announcer.js

@@ -0,0 +1,253 @@
+import { createInertRegistry, getInertRegistry, } from "../inert/index.js";
+import { appendRegion, createLiveRegion, resolveAppendTarget } from "./regions.js";
+import { ANNOUNCER_GLOBAL_KEY } from "./types.js";
+const DEFAULT_POLITE_DEBOUNCE_MS = 150;
+const DEFAULT_ASSERTIVE_DEBOUNCE_MS = 50;
+const DEFAULT_DEDUPE_MS = 1000;
+/** Gap after clearing a region before writing new text (SR re-announce). */
+const CLEAR_GAP_MS = 16;
+function defaultClock(documentRef) {
+    const view = documentRef.defaultView;
+    return {
+        now: () => (view?.performance?.now ? view.performance.now() : Date.now()),
+        setTimeout: (callback, ms) => {
+            if (view?.setTimeout)
+                return view.setTimeout(callback, ms);
+            return setTimeout(callback, ms);
+        },
+        clearTimeout: (id) => {
+            if (view?.clearTimeout)
+                view.clearTimeout(id);
+            else
+                clearTimeout(id);
+        },
+    };
+}
+function normalizeMessage(message) {
+    if (typeof message !== 'string')
+        return null;
+    const trimmed = message.replace(/\s+/g, ' ').trim();
+    return trimmed === '' ? null : trimmed;
+}
+function resolvePoliteness(options) {
+    if (options === 'polite' || options === 'assertive') {
+        return { politeness: options, immediate: false };
+    }
+    if (options && typeof options === 'object') {
+        return {
+            politeness: options.politeness === 'assertive' ? 'assertive' : 'polite',
+            immediate: options.immediate === true,
+        };
+    }
+    return { politeness: 'polite', immediate: false };
+}
+function resolveInertRegistry(option) {
+    if (option === null)
+        return null;
+    if (option)
+        return option;
+    try {
+        return getInertRegistry();
+    }
+    catch {
+        return createInertRegistry();
+    }
+}
+/**
+ * Create a live-region announcer bound to one document.
+ *
+ * Owns one polite (`role="status"`) and one assertive (`role="alert"`) region.
+ * Announcements are debounced per region, deduplicated, written with
+ * `textContent` only, and the region nodes are registered as inert exemptions
+ * so they keep working under modals.
+ */
+export function createAnnouncer(options) {
+    const documentRef = options.document;
+    if (!documentRef || typeof documentRef.createElement !== 'function') {
+        throw new TypeError('createAnnouncer: document must be a Document');
+    }
+    const clock = options.clock ?? defaultClock(documentRef);
+    const politeDebounceMs = options.politeDebounceMs ?? DEFAULT_POLITE_DEBOUNCE_MS;
+    const assertiveDebounceMs = options.assertiveDebounceMs ?? DEFAULT_ASSERTIVE_DEBOUNCE_MS;
+    const dedupeMs = options.dedupeMs ?? DEFAULT_DEDUPE_MS;
+    const inertRegistry = resolveInertRegistry(options.inertRegistry);
+    const inertLabel = options.inertLabel ?? 'announcer';
+    const polite = {
+        node: null,
+        pending: null,
+        timer: null,
+        clearTimer: null,
+        lastMessage: '',
+        lastAt: 0,
+        exemption: null,
+    };
+    const assertive = {
+        node: null,
+        pending: null,
+        timer: null,
+        clearTimer: null,
+        lastMessage: '',
+        lastAt: 0,
+        exemption: null,
+    };
+    let destroyed = false;
+    const stateOf = (politeness) => politeness === 'assertive' ? assertive : polite;
+    const ensureRegion = (politeness) => {
+        const state = stateOf(politeness);
+        if (state.node)
+            return state.node;
+        const node = createLiveRegion(documentRef, politeness);
+        const parent = resolveAppendTarget(documentRef, options.appendTo);
+        appendRegion(node, parent);
+        state.node = node;
+        if (inertRegistry) {
+            state.exemption = inertRegistry.exempt({
+                element: node,
+                label: `${inertLabel}:${politeness}`,
+            });
+        }
+        return node;
+    };
+    const cancelTimers = (state) => {
+        if (state.timer !== null) {
+            clock.clearTimeout(state.timer);
+            state.timer = null;
+        }
+        if (state.clearTimer !== null) {
+            clock.clearTimeout(state.clearTimer);
+            state.clearTimer = null;
+        }
+    };
+    const deliver = (politeness, message) => {
+        if (destroyed)
+            return;
+        const state = stateOf(politeness);
+        const now = clock.now();
+        if (dedupeMs > 0 && message === state.lastMessage && now - state.lastAt < dedupeMs) {
+            state.pending = null;
+            return;
+        }
+        const node = ensureRegion(politeness);
+        // Clear first so repeated identical text (after dedupe window) is re-read.
+        node.textContent = '';
+        cancelTimers(state);
+        state.clearTimer = clock.setTimeout(() => {
+            state.clearTimer = null;
+            if (destroyed || state.node !== node)
+                return;
+            node.textContent = message;
+            state.lastMessage = message;
+            state.lastAt = clock.now();
+            state.pending = null;
+        }, CLEAR_GAP_MS);
+    };
+    const flush = (politeness) => {
+        const state = stateOf(politeness);
+        state.timer = null;
+        const message = state.pending;
+        if (message === null)
+            return;
+        deliver(politeness, message);
+    };
+    const announcer = {
+        get regions() {
+            return {
+                get polite() {
+                    return ensureRegion('polite');
+                },
+                get assertive() {
+                    return ensureRegion('assertive');
+                },
+            };
+        },
+        ensure() {
+            if (destroyed)
+                return;
+            ensureRegion('polite');
+            ensureRegion('assertive');
+        },
+        announce(message, optionsOrPoliteness) {
+            if (destroyed)
+                return;
+            const text = normalizeMessage(message);
+            if (text === null)
+                return;
+            const { politeness, immediate } = resolvePoliteness(optionsOrPoliteness);
+            const state = stateOf(politeness);
+            state.pending = text;
+            if (immediate) {
+                cancelTimers(state);
+                deliver(politeness, text);
+                return;
+            }
+            if (state.timer !== null)
+                clock.clearTimeout(state.timer);
+            const delay = politeness === 'assertive' ? assertiveDebounceMs : politeDebounceMs;
+            if (delay <= 0) {
+                state.timer = null;
+                deliver(politeness, text);
+                return;
+            }
+            state.timer = clock.setTimeout(() => flush(politeness), delay);
+        },
+        clear() {
+            if (destroyed)
+                return;
+            for (const state of [polite, assertive]) {
+                cancelTimers(state);
+                state.pending = null;
+                state.lastMessage = '';
+                state.lastAt = 0;
+                if (state.node)
+                    state.node.textContent = '';
+            }
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            for (const state of [polite, assertive]) {
+                cancelTimers(state);
+                state.pending = null;
+                state.exemption?.release();
+                state.exemption = null;
+                state.node?.remove();
+                state.node = null;
+            }
+        },
+    };
+    return announcer;
+}
+/**
+ * Page-wide announcer for `documentRef`, stored on `globalObject` (default
+ * `globalThis`). Separate documents get separate instances.
+ */
+export function getAnnouncer(documentRef, options, globalObject = globalThis) {
+    let map = globalObject[ANNOUNCER_GLOBAL_KEY];
+    if (!map) {
+        map = new WeakMap();
+        globalObject[ANNOUNCER_GLOBAL_KEY] = map;
+    }
+    const existing = map.get(documentRef);
+    if (existing)
+        return existing;
+    const created = createAnnouncer({ ...options, document: documentRef });
+    map.set(documentRef, created);
+    return created;
+}
+/**
+ * Drop the shared announcer for `documentRef` (tests). Destroys the instance
+ * when one was stored.
+ */
+export function resetAnnouncer(documentRef, globalObject = globalThis) {
+    const map = globalObject[ANNOUNCER_GLOBAL_KEY];
+    if (!map)
+        return;
+    if (documentRef) {
+        const existing = map.get(documentRef);
+        existing?.destroy();
+        map.delete(documentRef);
+        return;
+    }
+    delete globalObject[ANNOUNCER_GLOBAL_KEY];
+}

package/dist/announcer/index.d.ts

@@ -0,0 +1,3 @@
+export { type AnnouncerGlobal, createAnnouncer, getAnnouncer, resetAnnouncer, } from './announcer.js';
+export { ANNOUNCER_REGION_ATTR, appendRegion, createLiveRegion, type RegionKind, resolveAppendTarget, } from './regions.js';
+export { ANNOUNCER_GLOBAL_KEY, type AnnounceOptions, type AnnouncePoliteness, type Announcer, type AnnouncerClock, type CreateAnnouncerOptions, } from './types.js';

package/dist/announcer/index.js

@@ -0,0 +1,3 @@
+export { createAnnouncer, getAnnouncer, resetAnnouncer, } from "./announcer.js";
+export { ANNOUNCER_REGION_ATTR, appendRegion, createLiveRegion, resolveAppendTarget, } from "./regions.js";
+export { ANNOUNCER_GLOBAL_KEY, } from "./types.js";

package/dist/announcer/regions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Visually hidden live-region nodes. Styles use logical properties and keep
+ * the node in the accessibility tree (no `display: none` / `visibility: hidden`
+ * / `aria-hidden`).
+ */
+export declare const ANNOUNCER_REGION_ATTR: "data-texuli-announcer";
+export type RegionKind = 'polite' | 'assertive';
+export declare function createLiveRegion(documentRef: Document, kind: RegionKind): HTMLElement;
+export declare function appendRegion(node: HTMLElement, parent: Element): void;
+export declare function resolveAppendTarget(documentRef: Document, appendTo?: Element): Element;

package/dist/announcer/regions.js

@@ -0,0 +1,46 @@
+/**
+ * Visually hidden live-region nodes. Styles use logical properties and keep
+ * the node in the accessibility tree (no `display: none` / `visibility: hidden`
+ * / `aria-hidden`).
+ */
+export const ANNOUNCER_REGION_ATTR = 'data-texuli-announcer';
+const HIDDEN_STYLE = [
+    'position: absolute',
+    'inline-size: 1px',
+    'block-size: 1px',
+    'margin: -1px',
+    'padding: 0',
+    'border: 0',
+    'overflow: hidden',
+    'clip: rect(0, 0, 0, 0)',
+    'white-space: nowrap',
+].join(';');
+export function createLiveRegion(documentRef, kind) {
+    const node = documentRef.createElement('div');
+    node.setAttribute(ANNOUNCER_REGION_ATTR, kind);
+    node.setAttribute('aria-live', kind);
+    node.setAttribute('aria-atomic', 'true');
+    if (kind === 'assertive') {
+        node.setAttribute('role', 'alert');
+    }
+    else {
+        node.setAttribute('role', 'status');
+    }
+    // Presentational hide; keep in a11y tree. CSSOM, not a `style` attribute,
+    // which a strict CSP (`style-src` without 'unsafe-inline') blocks.
+    node.style.cssText = HIDDEN_STYLE;
+    node.textContent = '';
+    return node;
+}
+export function appendRegion(node, parent) {
+    if (node.parentNode === parent)
+        return;
+    parent.appendChild(node);
+}
+export function resolveAppendTarget(documentRef, appendTo) {
+    if (appendTo)
+        return appendTo;
+    if (documentRef.body)
+        return documentRef.body;
+    return documentRef.documentElement;
+}

package/dist/announcer/types.d.ts

@@ -0,0 +1,68 @@
+import type { InertRegistry } from '../inert/index.js';
+/** Live-region politeness. One DOM region exists per value per announcer. */
+export type AnnouncePoliteness = 'polite' | 'assertive';
+/**
+ * Clock used for debounce and dedupe. Defaults to the document's window
+ * timers / `Date.now`. Tests inject a fake.
+ */
+export interface AnnouncerClock {
+    now: () => number;
+    setTimeout: (callback: () => void, ms: number) => unknown;
+    clearTimeout: (id: unknown) => void;
+}
+export interface CreateAnnouncerOptions {
+    /** Document that owns the live regions (required; no import-time DOM). */
+    document: Document;
+    /**
+     * Parent for the region nodes. Defaults to `document.body` when present,
+     * otherwise `document.documentElement`.
+     */
+    appendTo?: Element;
+    /** Debounce for polite announcements in ms (default 150). */
+    politeDebounceMs?: number;
+    /** Debounce for assertive announcements in ms (default 50). */
+    assertiveDebounceMs?: number;
+    /**
+     * Skip a message identical to the last one delivered on the same region
+     * within this many ms (default 1000). `0` disables dedupe.
+     */
+    dedupeMs?: number;
+    /**
+     * Inert registry used to exempt the region nodes under modals. Defaults to
+     * the page-wide registry when the option is omitted; pass `null` to skip
+     * registration (tests).
+     */
+    inertRegistry?: InertRegistry | null;
+    /** Optional debug label prefix for inert exemptions. */
+    inertLabel?: string;
+    /** Timer / now source (tests). */
+    clock?: AnnouncerClock;
+}
+export interface AnnounceOptions {
+    politeness?: AnnouncePoliteness;
+    /**
+     * When true, bypass debounce and deliver on the next task (still clears the
+     * region first so repeated text is re-read).
+     */
+    immediate?: boolean;
+}
+export interface Announcer {
+    /**
+     * Queue `message` for the polite or assertive region. Empty / whitespace
+     * messages are ignored. Text is set via `textContent` only (no HTML).
+     */
+    announce: (message: string, options?: AnnounceOptions | AnnouncePoliteness) => void;
+    /** Clear both regions and cancel pending debounced work. */
+    clear: () => void;
+    /** Remove nodes, release inert exemptions, cancel timers. Idempotent. */
+    destroy: () => void;
+    /** The live-region elements (created lazily on first announce or ensure). */
+    readonly regions: {
+        readonly polite: HTMLElement;
+        readonly assertive: HTMLElement;
+    };
+    /** Force-create both regions and register exemptions without announcing. */
+    ensure: () => void;
+}
+/** Versioned key for a page-wide announcer map on `globalThis`. */
+export declare const ANNOUNCER_GLOBAL_KEY: "__TEXULI_ANNOUNCER_V1__";

package/dist/announcer/types.js

@@ -0,0 +1,2 @@
+/** Versioned key for a page-wide announcer map on `globalThis`. */
+export const ANNOUNCER_GLOBAL_KEY = '__TEXULI_ANNOUNCER_V1__';

package/dist/controllable/controllable-state.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Options for a state value that may be controlled by its owner.
+ *
+ * Supplying `value` makes the state controlled for this helper's lifetime.
+ * The getter is read each time so rune-backed props remain reactive. Without
+ * it, `defaultValue` initializes local state once.
+ */
+export interface ControllableStateOptions<T> {
+    /** Current owner-provided value. Omit this getter for uncontrolled state. */
+    value?: () => T;
+    /** Initial value used only when `value` is omitted. */
+    defaultValue: T;
+    /** Called when a requested value differs from the current value. */
+    onChange?: (value: T) => void;
+    /** Called only when the owner explicitly marks a change as complete. */
+    onChangeComplete?: (value: T) => void;
+}
+/**
+ * A rune-friendly view of controlled or local state.
+ *
+ * `value` reads the owner's getter when controlled, or the local value
+ * otherwise. `setValue` and `update` request changes; controlled state is
+ * never mutated locally. Call `complete` at the interaction boundary (for
+ * example pointer-up or blur) to invoke `onChangeComplete`. This helper does
+ * not attach listeners, schedule callbacks, or access browser globals.
+ */
+export interface ControllableState<T> {
+    /** The current controlled or uncontrolled value. */
+    readonly value: T;
+    /** Request an explicit value. Equal values are ignored using `Object.is`. */
+    setValue(value: T): void;
+    /** Request a value derived from the latest current value. */
+    update(updater: (current: T) => T): void;
+    /** Signal that the caller's interaction is complete. */
+    complete(): void;
+}
+/**
+ * Creates framework-free state for props that support controlled (`bind:`)
+ * and uncontrolled (`defaultValue`) use.
+ *
+ * The `value` getter is read at access time, so a Svelte rune-backed prop can
+ * be passed without taking a stale snapshot. Controlledness is fixed when the
+ * helper is created: provide or omit `value` consistently for its lifetime.
+ *
+ * `onChange` runs synchronously only when a new value is requested. In
+ * controlled mode the owner remains the source of truth and must update its
+ * value in response. `onChangeComplete` runs only when the caller invokes
+ * `complete`, and receives the then-current value.
+ */
+export declare function createControllableState<T>(options: ControllableStateOptions<T>): ControllableState<T>;

package/dist/controllable/controllable-state.js

@@ -0,0 +1,40 @@
+/**
+ * Creates framework-free state for props that support controlled (`bind:`)
+ * and uncontrolled (`defaultValue`) use.
+ *
+ * The `value` getter is read at access time, so a Svelte rune-backed prop can
+ * be passed without taking a stale snapshot. Controlledness is fixed when the
+ * helper is created: provide or omit `value` consistently for its lifetime.
+ *
+ * `onChange` runs synchronously only when a new value is requested. In
+ * controlled mode the owner remains the source of truth and must update its
+ * value in response. `onChangeComplete` runs only when the caller invokes
+ * `complete`, and receives the then-current value.
+ */
+export function createControllableState(options) {
+    let localValue = options.defaultValue;
+    const controlledValue = options.value;
+    const isControlled = controlledValue !== undefined;
+    const read = () => (controlledValue ? controlledValue() : localValue);
+    const request = (next) => {
+        if (Object.is(read(), next))
+            return;
+        if (!isControlled)
+            localValue = next;
+        options.onChange?.(next);
+    };
+    return {
+        get value() {
+            return read();
+        },
+        setValue(value) {
+            request(value);
+        },
+        update(updater) {
+            request(updater(read()));
+        },
+        complete() {
+            options.onChangeComplete?.(read());
+        },
+    };
+}