@texuli/core 0.5.0 → 0.7.0

package/README.md

@@ -12,9 +12,9 @@ when you need Texuli's URL policy to sanitize links and media from agents
 or users. It has no runtime dependencies and imports no UI framework.
 
 > **Status: 0.x release.** Texuli is in development. The packages are
-> published to npm as `0.5.0`, a pre-1.0 release (1.0.0 will be the first
-> stable release). Under 0.x, a new minor (`0.6.0`) may contain breaking
-> changes, so pin the exact version or use `^0.5.0`, which accepts only 0.5.x.
+> published to npm as `0.7.0`, a pre-1.0 release (1.0.0 will be the first
+> stable release). Under 0.x, a new minor (`0.8.0`) may contain breaking
+> changes, so pin the exact version or use `^0.7.0`, which accepts only 0.7.x.
 
 ## Install
 
@@ -59,8 +59,8 @@ window.addEventListener('keydown', (event) => {
 
 Everything in the table below is available from the root entry
 (`@texuli/core`) and from its own subpath (`@texuli/core/<subpath>`), except
-the editor and lazy-chunk texels, which are subpath-only. Import subpaths to
-keep bundles narrow.
+the editor, lazy-chunk, motion, markup and ZIP texels, which are
+subpath-only. Import subpaths to keep bundles narrow.
 
 ## What's inside
 
@@ -88,6 +88,8 @@ keep bundles narrow.
 | Environment | `env` | `isBrowser`, `getOwnerDocument`, `listen`, `matchesMedia`, `requestFrame` |
 | Lazy chunks | `lazy` | `lazyChunk`, `hasLazyChunk` (subpath only) |
 | Rich text editor model | `editor-model`, `editor-transforms`, `editor-history`, `editor-keymap`, `editor-markdown` | Document model, transforms, undo history, keymap, Markdown import and export (subpath only) |
+| Markup builders | `markup` | `el`, `text`, `linkUrl`, `imageUrl`, `serializeXml`, `serializeHtml`: escaped XML and HTML with no raw-markup API (subpath only) |
+| ZIP writer | `zip` | `writeZip`, `writeZipAsync`, `crc32`, `compressBytes`: deterministic archives, deflated where the platform can (subpath only) |
 
 The table names the headline exports; each subpath's TypeScript
 declarations list the full surface.
@@ -123,6 +125,26 @@ through this policy, and you can use it the same way. Rejected values return
 - **Right-to-left aware.** Direction helpers map logical sides to physical
   ones, and positioning resolves placements for the current direction.
 
+## New in 0.6.0
+
+Ships in `0.6.0`; the `0.5.0` release predates it:
+
+- `@texuli/core/motion` and `@texuli/core/motion/spring`: presence, FLIP
+  layout, shared elements, sequences and timelines, and an owned spring
+  solver over the Web Animations API, instant on the server and under
+  reduced motion ([core-motion](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-motion.md)).
+- `@texuli/core/markup` and `@texuli/core/zip`: escaped XML and HTML
+  builders and a deterministic ZIP writer for static outputs
+  ([core-markup](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-markup.md),
+  [core-zip](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-zip.md)).
+- Inline extensions in the editor model and Markdown codec (G48:
+  `createInlineExtensions`, the `extension` mark and `<sigil>{id|label}`
+  tokens), and a reader that is linear on long plain text
+  ([core-editor](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-editor.md)).
+- Inert exemptions take `raise: false`, so an overlay opened inside a modal
+  dialog stays above its backdrop (G75,
+  [core-inert](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-inert.md)).
+
 ## Documentation
 
 - Website: [texuli.com](https://texuli.com) and the
@@ -134,6 +156,8 @@ through this policy, and you can use it the same way. Rejected values return
 - Positioning: [core-position-math.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-position-math.md)
   and [core-position-dom.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-position-dom.md)
 - Rich text editor model: [core-editor.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-editor.md)
+- Static outputs: [core-markup.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-markup.md) (escaped XML and HTML builders) and [core-zip.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-zip.md) (the ZIP writer)
+- Motion (`@texuli/core/motion`: animate, presence, FLIP, shared elements, timelines, springs): [core-motion.md](https://github.com/DailybotHQ/texuli/blob/main/packages/core/docs/core-motion.md)
 - Every texel's contract: [packages/core/docs](https://github.com/DailybotHQ/texuli/tree/main/packages/core/docs)
 - Security model: [SECURITY.md](https://github.com/DailybotHQ/texuli/blob/main/docs/SECURITY.md)
 

package/dist/editor/document.js

@@ -303,7 +303,14 @@ export function validateEditorDocument(doc) {
                 if (mark?.type === 'link' && (typeof mark.href !== 'string' || mark.href === '')) {
                     issues.push(issue('invalid-shape', 'A link mark has an href.', id));
                 }
-                else if (!['link', 'strong', 'em', 'strike', 'code'].includes(mark?.type)) {
+                else if (mark?.type === 'extension' &&
+                    (typeof mark.name !== 'string' ||
+                        mark.name === '' ||
+                        typeof mark.id !== 'string' ||
+                        mark.id === '')) {
+                    issues.push(issue('invalid-shape', 'An extension mark has a name and an id.', id));
+                }
+                else if (!['link', 'strong', 'em', 'strike', 'code', 'extension'].includes(mark?.type)) {
                     issues.push(issue('unknown-mark', `Unknown mark "${String(mark?.type)}".`, id));
                 }
             }

package/dist/editor/extensions.d.ts

@@ -0,0 +1,64 @@
+import { type HrefTrust } from '../url/safe-href.js';
+/**
+ * Host inline extensions (G48): closed, host-registered inline entities such
+ * as mentions (`@{person-1|Ada}`) and references (`#{rec-7|Roadmap}`). In the
+ * model an entity is an `extension` mark (`name` and `id`) over its label
+ * text, so offsets, selections and transforms stay plain text. In Markdown
+ * it is the delimiter grammar `<sigil>{<id>|<label>}`.
+ *
+ * The grammar is fixed and read in linear time: a host registers a name and
+ * a sigil from a closed set, never a pattern. A host `accepts` check sees
+ * only ids that already passed the bounded id charset; a host `href` is
+ * always checked by the URL policy (`untrusted` by default).
+ */
+/** The sigils an extension can open with. */
+export declare const EDITOR_EXTENSION_SIGILS: readonly ["@", "#", "$", "%", "&", "+", "=", "^"];
+export type EditorExtensionSigil = (typeof EDITOR_EXTENSION_SIGILS)[number];
+export declare const EDITOR_EXTENSION_LIMITS: Readonly<{
+    /** Registered extensions. */
+    extensions: 16;
+    /** Longest entity id: `[A-Za-z0-9_.:-]`. */
+    id: 128;
+    /** Longest label read from Markdown. */
+    label: 512;
+}>;
+/** The id charset, one character at a time (no regex on untrusted runs). */
+export declare function isExtensionIdChar(code: number): boolean;
+export interface EditorInlineExtension {
+    /** Stored on the mark: `[a-z][a-z0-9-]{0,31}`, unique in a registry. */
+    name: string;
+    /** Opens `<sigil>{id|label}`; one of `EDITOR_EXTENSION_SIGILS`, unique in a registry. */
+    sigil: EditorExtensionSigil;
+    /** Optional host check of an id that already passed the charset and length cap. */
+    accepts?: (id: string) => boolean;
+    /** Optional link for an entity; `extensionHref` checks it with the URL policy. */
+    href?: (id: string) => string | undefined;
+}
+/** A validated, frozen set of extensions (from `createInlineExtensions`). */
+export interface EditorInlineExtensions {
+    readonly list: readonly EditorInlineExtension[];
+    readonly bySigil: ReadonlyMap<string, EditorInlineExtension>;
+    readonly byName: ReadonlyMap<string, EditorInlineExtension>;
+    /** Characters that can start an inline construct, sigils included. Internal. */
+    readonly special: RegExp;
+    /** A sigil followed by `{` in plain text (escaped when written). Internal. */
+    readonly literal: RegExp | null;
+}
+/**
+ * Validate a host's extensions once. Throws a `TypeError` on a bad name or
+ * sigil, a duplicate, or more than 16 entries: these are developer errors.
+ */
+export declare function createInlineExtensions(list?: readonly EditorInlineExtension[]): EditorInlineExtensions;
+/** A registry from either form; `undefined` gives the empty one. */
+export declare function toInlineExtensions(value: EditorInlineExtensions | readonly EditorInlineExtension[] | undefined): EditorInlineExtensions;
+/** Whether `id` is a usable entity id for the registered `name`. */
+export declare function acceptsExtensionId(registry: EditorInlineExtensions, name: unknown, id: unknown): boolean;
+/**
+ * The policy-checked link of an entity, or `undefined` when the extension
+ * has no `href`, the host throws, or the URL policy refuses it. Untrusted by
+ * default: entity ids come from agent or user content.
+ */
+export declare function extensionHref(registry: EditorInlineExtensions, mark: {
+    name: string;
+    id: string;
+}, trust?: HrefTrust): string | undefined;

package/dist/editor/extensions.js

@@ -0,0 +1,116 @@
+import { safeHref } from "../url/safe-href.js";
+/**
+ * Host inline extensions (G48): closed, host-registered inline entities such
+ * as mentions (`@{person-1|Ada}`) and references (`#{rec-7|Roadmap}`). In the
+ * model an entity is an `extension` mark (`name` and `id`) over its label
+ * text, so offsets, selections and transforms stay plain text. In Markdown
+ * it is the delimiter grammar `<sigil>{<id>|<label>}`.
+ *
+ * The grammar is fixed and read in linear time: a host registers a name and
+ * a sigil from a closed set, never a pattern. A host `accepts` check sees
+ * only ids that already passed the bounded id charset; a host `href` is
+ * always checked by the URL policy (`untrusted` by default).
+ */
+/** The sigils an extension can open with. */
+export const EDITOR_EXTENSION_SIGILS = ['@', '#', '$', '%', '&', '+', '=', '^'];
+export const EDITOR_EXTENSION_LIMITS = Object.freeze({
+    /** Registered extensions. */
+    extensions: 16,
+    /** Longest entity id: `[A-Za-z0-9_.:-]`. */
+    id: 128,
+    /** Longest label read from Markdown. */
+    label: 512,
+});
+const NAME = /^[a-z][a-z0-9-]{0,31}$/;
+const ID = /^[A-Za-z0-9_.:-]+$/;
+/** The id charset, one character at a time (no regex on untrusted runs). */
+export function isExtensionIdChar(code) {
+    return ((code >= 48 && code <= 58) || // 0-9 and ':'
+        (code >= 65 && code <= 90) ||
+        (code >= 97 && code <= 122) ||
+        code === 95 || // _
+        code === 46 || // .
+        code === 45 // -
+    );
+}
+const BASE_SPECIAL = '\\\\\\n`*_~!\\[<';
+const reEscape = (char) => char.replace(/[$^+\\]/g, '\\$&');
+const EMPTY = Object.freeze({
+    list: Object.freeze([]),
+    bySigil: new Map(),
+    byName: new Map(),
+    special: new RegExp(`[${BASE_SPECIAL}]`, 'g'),
+    literal: null,
+});
+/**
+ * Validate a host's extensions once. Throws a `TypeError` on a bad name or
+ * sigil, a duplicate, or more than 16 entries: these are developer errors.
+ */
+export function createInlineExtensions(list = []) {
+    if (list.length === 0)
+        return EMPTY;
+    if (list.length > EDITOR_EXTENSION_LIMITS.extensions)
+        throw new TypeError('Too many extensions.');
+    const bySigil = new Map();
+    const byName = new Map();
+    for (const extension of list) {
+        const { name, sigil } = extension ?? {};
+        if (typeof name !== 'string' ||
+            !NAME.test(name) ||
+            !EDITOR_EXTENSION_SIGILS.includes(sigil) ||
+            byName.has(name) ||
+            bySigil.has(sigil))
+            throw new TypeError(`Bad or repeated inline extension "${String(name)}" (${String(sigil)}).`);
+        const frozen = Object.freeze({ ...extension });
+        byName.set(name, frozen);
+        bySigil.set(sigil, frozen);
+    }
+    const sigils = [...bySigil.keys()].map(reEscape).join('');
+    return Object.freeze({
+        list: Object.freeze([...byName.values()]),
+        bySigil,
+        byName,
+        special: new RegExp(`[${BASE_SPECIAL}${sigils}]`, 'g'),
+        literal: new RegExp(`([${sigils}])\\{`, 'g'),
+    });
+}
+/** A registry from either form; `undefined` gives the empty one. */
+export function toInlineExtensions(value) {
+    if (!value)
+        return EMPTY;
+    return Array.isArray(value)
+        ? createInlineExtensions(value)
+        : value;
+}
+/** Whether `id` is a usable entity id for the registered `name`. */
+export function acceptsExtensionId(registry, name, id) {
+    if (typeof name !== 'string' || typeof id !== 'string')
+        return false;
+    const extension = registry.byName.get(name);
+    if (!extension || id.length === 0 || id.length > EDITOR_EXTENSION_LIMITS.id || !ID.test(id))
+        return false;
+    try {
+        return extension.accepts ? extension.accepts(id) === true : true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The policy-checked link of an entity, or `undefined` when the extension
+ * has no `href`, the host throws, or the URL policy refuses it. Untrusted by
+ * default: entity ids come from agent or user content.
+ */
+export function extensionHref(registry, mark, trust = 'untrusted') {
+    const extension = registry.byName.get(mark.name);
+    if (!extension?.href || !acceptsExtensionId(registry, mark.name, mark.id))
+        return undefined;
+    let href;
+    try {
+        href = extension.href(mark.id);
+    }
+    catch {
+        return undefined;
+    }
+    return typeof href === 'string' ? safeHref(href, trust) : undefined;
+}

package/dist/editor/inline.d.ts

@@ -11,12 +11,13 @@ export declare function cleanText(text: string, keep?: string): {
     text: string;
     stripped: boolean;
 };
-/** The identity of a mark: its type, plus the href for links. */
+/** The identity of a mark: its type, plus the href for links and the entity for extensions. */
 export declare const markKey: (mark: EditorMark) => string;
 export declare const hasMark: (marks: readonly EditorMark[], type: EditorMarkType) => boolean;
 /**
  * Canonical mark set: one mark per type (the first wins), sorted in
- * `EDITOR_MARK_ORDER`, and `code` excludes every mark but `link`.
+ * `EDITOR_MARK_ORDER`; `extension` excludes `link` and `code`, and `code`
+ * excludes every other mark but `link`.
  */
 export declare function sortMarks(marks: readonly EditorMark[]): readonly EditorMark[];
 export declare const sameMarks: (a: readonly EditorMark[], b: readonly EditorMark[]) => boolean;
@@ -38,7 +39,8 @@ export declare const concatInline: (...parts: (readonly EditorInline[])[]) => re
 export declare const spliceInline: (content: readonly EditorInline[], from: number, to: number, insert?: readonly EditorInline[]) => readonly EditorInline[];
 /**
  * The marks text typed at `offset` gets: those of the character before (the
- * first character at offset 0). A link continues only strictly inside it.
+ * first character at offset 0). A link or an extension entity continues only
+ * strictly inside it.
  */
 export declare function inheritedMarks(content: readonly EditorInline[], offset: number): readonly EditorMark[];
 /** Apply `update` to the marks of every text character in `[from, to)`. */

package/dist/editor/inline.js

@@ -36,22 +36,29 @@ export function cleanText(text, keep = '') {
     }
     return { text: out, stripped };
 }
-/** The identity of a mark: its type, plus the href for links. */
-export const markKey = (mark) => mark.type === 'link' ? `link:${mark.href}` : mark.type;
+/** The identity of a mark: its type, plus the href for links and the entity for extensions. */
+export const markKey = (mark) => mark.type === 'link'
+    ? `link:${mark.href}`
+    : mark.type === 'extension'
+        ? `extension:${mark.name}:${mark.id}`
+        : mark.type;
 export const hasMark = (marks, type) => marks.some((mark) => mark.type === type);
 /**
  * Canonical mark set: one mark per type (the first wins), sorted in
- * `EDITOR_MARK_ORDER`, and `code` excludes every mark but `link`.
+ * `EDITOR_MARK_ORDER`; `extension` excludes `link` and `code`, and `code`
+ * excludes every other mark but `link`.
  */
 export function sortMarks(marks) {
     const byType = new Map();
     for (const mark of marks)
         if (!byType.has(mark.type))
             byType.set(mark.type, mark);
-    const code = byType.has('code');
+    const extension = byType.has('extension');
+    const code = !extension && byType.has('code');
+    const keep = (type) => extension ? type !== 'link' && type !== 'code' : !code || type === 'link' || type === 'code';
     const out = EDITOR_MARK_ORDER.flatMap((type) => {
         const mark = byType.get(type);
-        return mark && (!code || type === 'link' || type === 'code') ? [mark] : [];
+        return mark && keep(type) ? [mark] : [];
     });
     return out.length === marks.length && out.every((mark, i) => mark === marks[i]) ? marks : out;
 }
@@ -130,17 +137,22 @@ function textAt(content, offset) {
 }
 /**
  * The marks text typed at `offset` gets: those of the character before (the
- * first character at offset 0). A link continues only strictly inside it.
+ * first character at offset 0). A link or an extension entity continues only
+ * strictly inside it.
  */
 export function inheritedMarks(content, offset) {
     const before = offset > 0 ? textAt(content, offset - 1) : undefined;
     const after = textAt(content, offset);
-    const marks = (offset > 0 ? before : after)?.marks ?? [];
-    const link = marks.find((mark) => mark.type === 'link');
-    const inside = link !== undefined &&
-        before !== undefined &&
-        after?.marks.some((mark) => markKey(mark) === markKey(link)) === true;
-    return link && !inside ? withoutMark(marks, 'link') : marks;
+    let marks = (offset > 0 ? before : after)?.marks ?? [];
+    for (const type of ['link', 'extension']) {
+        const edge = marks.find((mark) => mark.type === type);
+        const inside = edge !== undefined &&
+            before !== undefined &&
+            after?.marks.some((mark) => markKey(mark) === markKey(edge)) === true;
+        if (edge && !inside)
+            marks = withoutMark(marks, type);
+    }
+    return marks;
 }
 /** Apply `update` to the marks of every text character in `[from, to)`. */
 export function mapMarks(content, from, to, update) {

package/dist/editor/load.d.ts

@@ -1,5 +1,6 @@
 import type { HrefTrust } from '../url/safe-href.js';
 import { type EditorIdSource } from './document.js';
+import { type EditorInlineExtension, type EditorInlineExtensions } from './extensions.js';
 import { type EditorDocument, type EditorInline, type EditorIssue, type EditorIssueCode, type EditorLimits, type EditorMark } from './types.js';
 export interface EditorLoadOptions {
     /** URL policy tier for link hrefs. Default `untrusted`. */
@@ -7,6 +8,12 @@ export interface EditorLoadOptions {
     newId?: EditorIdSource;
     /** Lower caps (a blocks `text` field holds 4,000 characters). */
     limits?: Partial<EditorLimits>;
+    /**
+     * Host inline extensions whose `extension` marks are kept (mentions,
+     * references). Marks of other names, or with a refused id, are dropped and
+     * keep their label text. None by default.
+     */
+    extensions?: EditorInlineExtensions | readonly EditorInlineExtension[];
 }
 export interface EditorLoadResult {
     doc: EditorDocument;
@@ -18,10 +25,13 @@ export declare class LoadBudget {
     readonly limits: EditorLimits;
     readonly trust: HrefTrust;
     readonly newId: EditorIdSource;
+    readonly extensions: EditorInlineExtensions;
     blocks: number;
     chars: number;
     private readonly once;
     constructor(options: EditorLoadOptions);
+    /** An extension mark for a registered name and an accepted id, or `undefined` (reported). */
+    extension(name: unknown, id: unknown): EditorMark | undefined;
     report(code: EditorIssueCode, message: string, onlyOnce?: boolean): void;
     /** Reserve one block; false (reported) once the cap is reached. */
     block(): boolean;

package/dist/editor/load.js

@@ -1,5 +1,6 @@
 import { safeHref } from "../url/safe-href.js";
 import { LANG_PATTERN, nextEditorId, normalizeDocument, paragraph, } from "./document.js";
+import { acceptsExtensionId, toInlineExtensions, } from "./extensions.js";
 import { cleanText, normalizeInline, textToInline } from "./inline.js";
 import { EDITOR_LIMITS, } from "./types.js";
 const MAX_DIAGNOSTICS = 50;
@@ -9,6 +10,7 @@ export class LoadBudget {
     limits;
     trust;
     newId;
+    extensions;
     blocks = 0;
     chars = 0;
     once = new Set();
@@ -16,6 +18,14 @@ export class LoadBudget {
         this.limits = { ...EDITOR_LIMITS, ...options.limits };
         this.trust = options.trust === 'developer' ? 'developer' : 'untrusted';
         this.newId = options.newId ?? nextEditorId;
+        this.extensions = toInlineExtensions(options.extensions);
+    }
+    /** An extension mark for a registered name and an accepted id, or `undefined` (reported). */
+    extension(name, id) {
+        if (acceptsExtensionId(this.extensions, name, id))
+            return { type: 'extension', name: name, id: id };
+        this.report('mark-dropped', 'Unregistered or refused inline extensions kept only their text.');
+        return undefined;
     }
     report(code, message, onlyOnce = true) {
         if (onlyOnce && this.once.has(code))
@@ -96,6 +106,12 @@ function loadMarks(raw, budget) {
             if (href)
                 marks.push({ type: 'link', href });
         }
+        else if (type === 'extension') {
+            const record = mark;
+            const extension = budget.extension(record.name, record.id);
+            if (extension)
+                marks.push(extension);
+        }
         else
             budget.report('unknown-mark', 'Unknown marks were dropped.');
     }

package/dist/editor/markdown.d.ts

@@ -1,3 +1,4 @@
+import { type EditorInlineExtension, type EditorInlineExtensions } from './extensions.js';
 import { type EditorLoadOptions, type EditorLoadResult } from './load.js';
 import type { EditorDocument } from './types.js';
 /**
@@ -17,6 +18,14 @@ export interface MarkdownReadOptions extends EditorLoadOptions {
     /** Override the source cap (a blocks `text` field holds 4,000 characters). */
     maxSource?: number;
 }
+export interface MarkdownWriteOptions {
+    /**
+     * Host inline extensions written as `<sigil>{id|label}`. Extension marks of
+     * other names are written as their label text, and plain text that would
+     * read as a token gets its `{` escaped.
+     */
+    extensions?: EditorInlineExtensions | readonly EditorInlineExtension[];
+}
 /**
  * Read Markdown (untrusted by default) into a valid document. Never throws:
  * nesting deeper than the depth cap and oversized input degrade to text,
@@ -30,4 +39,4 @@ export declare function fromMarkdown(source: unknown, options?: MarkdownReadOpti
  * paragraphs, breaks in headings (written as spaces), breaks at the edges of
  * a block, and whitespace at the edges of a paragraph or a mark.
  */
-export declare function toMarkdown(doc: EditorDocument): string;
+export declare function toMarkdown(doc: EditorDocument, options?: MarkdownWriteOptions): string;