@jini-ai/cms 0.5.5 → 0.5.6

package/dist/forms/submit-service.js

@@ -46,10 +46,15 @@ export async function submitForm(required, optional = {}) {
     if (isHoneypotTripped({ hp: input.body[HONEYPOT_KEY] })) {
         return { status: "accepted" };
     }
-    const validation = validateSubmissionPayload({ definition, body: input.body });
+    const validation = validateSubmissionPayload({ definition, body: input.body }, deps.files ? { files: deps.files } : {});
     if (!validation.valid) {
         throw new FormSubmissionValidationError({ message: "submission failed field validation", fieldErrors: validation.fieldErrors });
     }
+    if (validation.files && !deps.transaction) {
+        // Without rollback, a failed outbox write would leave a stored row pointing at compensated
+        // files. Existing scalar-only hosts retain their legacy optional-transaction contract.
+        throw new FormSubmissionValidationError({ message: "file submissions require transactional storage", fieldErrors: Object.keys(validation.files).map((field) => ({ field, reason: "file_storage_unavailable" })) });
+    }
     // Scope by both IP and form so one client's different forms cannot cross-throttle each other.
     const rateLimitKey = buildFormsRateLimitKey({ sourceIp: input.sourceIp, formDefinitionId: definition.id });
     const rateLimitResult = await deps.rateLimiter.check({ key: rateLimitKey });
@@ -77,10 +82,38 @@ export async function submitForm(required, optional = {}) {
     // Only a persisted accepted submission gets this event; honeypot discards emit nothing. Row and
     // event commit together: a failed enqueue must not leave a stored submission nobody is told about.
     const transaction = deps.transaction ?? ((work) => work());
-    const persist = () => transaction(async () => {
-        await deps.submissionRepo.create(submission);
-        await deps.outbox.enqueue(event);
-    });
+    const persist = async () => {
+        // Blob backends cannot participate in a SQL transaction. Store within the dedupe claim,
+        // then compensate only this attempt's new media assets when any upload/row/event write fails.
+        // Byte buffers never reach data_json, notifications or the outbox payload.
+        const uploaded = [];
+        try {
+            for (const [fieldId, file] of Object.entries(validation.files ?? {})) {
+                const reference = await deps.files.store({ workspaceId: input.workspaceId, submissionId, fieldId, file });
+                uploaded.push(reference);
+                submission.data[fieldId] = reference;
+            }
+            await transaction(async () => {
+                await deps.submissionRepo.create(submission);
+                await deps.outbox.enqueue(event);
+            });
+        }
+        catch (error) {
+            for (const reference of uploaded) {
+                try {
+                    await deps.files.discard({ workspaceId: input.workspaceId, reference });
+                }
+                catch (cleanupError) {
+                    // Retain the original submission failure; a failed cleanup is visible to operators.
+                    try {
+                        deps.logger.warn({ message: "form upload cleanup failed" }, { error: cleanupError });
+                    }
+                    catch { /* Logging cannot replace the original error. */ }
+                }
+            }
+            throw error;
+        }
+    };
     if (optional.attempts) {
         // The attempt is claimed only where persistence begins, after validation and rate limiting.
         // A copy waits outside the database transaction; failed first copies free the claim for retry.

package/dist/forms/types.d.ts

@@ -1,12 +1,30 @@
 import type { UUID } from "@jini-ai/core/primitives";
-export type FieldType = "text" | "email" | "textarea" | "checkbox";
+export type FieldType = keyof typeof import("./field-registry.js").FIELD_TYPE_REGISTRY;
 export type FormDefinitionStatus = "active" | "disabled";
 export interface FieldDescriptor {
     id: string;
     label: string;
     type: FieldType;
     required: boolean;
+    /** Optional HTML name; must equal the stable id so historic submission keys remain valid. */
+    name?: string;
+    placeholder?: string;
+    helpText?: string;
+    default?: string | number | boolean | string[];
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    minLength?: number;
     maxLength?: number | null;
+    /** Full-match, bounded safe regular expression; groups/alternation/backreferences are refused. */
+    pattern?: string;
+    min?: number | string;
+    max?: number | string;
+    step?: number;
+    /** Omitted accept means every recognized safe type, never executable/markup/archive formats. */
+    accept?: string[];
+    maxFileSize?: number;
     /** Presence distinguishes an authored checkbox value (even "") from the native boolean default. */
     checkboxValue?: string;
     /** Length-bounded and HTML-escaped at rendering; class names are inert after escaping. */
@@ -37,7 +55,7 @@ export interface FormSubmissionRecord {
     id: UUID;
     workspaceId: UUID;
     formDefinitionId: UUID;
-    data: Record<string, string | boolean>;
+    data: Record<string, FormAnswer>;
     /** Cleared by metadata retention; answers and the submission itself remain. */
     sourceIp: string | null;
     submittedAt: string;
@@ -46,4 +64,34 @@ export interface FormSubmissionPage {
     items: FormSubmissionRecord[];
     nextCursor: string | null;
 }
+/** Byte-bearing input exists only in memory at the submission boundary. Never stored as JSON. */
+export interface FormFileInput {
+    filename: string;
+    contentType: string;
+    bytes: Uint8Array;
+}
+export interface FormFileReference {
+    mediaId: string;
+    filename: string;
+    contentType: string;
+    byteSize: number;
+}
+export type FormAnswer = string | boolean | number | string[] | FormFileReference;
+/** Hosts sniff bytes and persist accepted originals via their existing media/storage owner. */
+export interface FormFileStoragePort {
+    detectContentType(required: {
+        bytes: Uint8Array;
+    }, optional?: Record<string, never>): string;
+    store(required: {
+        workspaceId: string;
+        submissionId: string;
+        fieldId: string;
+        file: FormFileInput;
+    }, optional?: Record<string, never>): Promise<FormFileReference>;
+    /** Compensates originals created by this attempt if the submission transaction fails. */
+    discard(required: {
+        workspaceId: string;
+        reference: FormFileReference;
+    }, optional?: Record<string, never>): Promise<void>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/listing/batch.d.ts

@@ -0,0 +1,53 @@
+/**
+ * "See more" listing batches: the one read rule every progressive listing (posts, collections, a
+ * future JSON endpoint) shares. `after`/`next` count SOURCE rows already consumed, not visible ones,
+ * so visibility (member access included) is applied before items are taken and a hidden row is
+ * never counted twice or shown out of order.
+ */
+/** Batch size a see-more listing uses when its config names none. */
+export declare const LISTING_BATCH_DEFAULT = 12;
+/** Ceiling on one batch, so neither an absent nor an adversarial config turns a listing into a scan. */
+export declare const LISTING_BATCH_MAX = 24;
+/** Ceiling on the source cursor: OFFSET cost is O(after), so a forged huge cursor is refused. */
+export declare const LISTING_AFTER_MAX = 100000;
+/** Reads `limit` source rows starting `offset` rows in, in the listing's own stable order. */
+export type ListingSource<T> = (page: {
+    offset: number;
+    limit: number;
+}) => Promise<readonly T[]>;
+export interface ListingBatch<T> {
+    readonly items: readonly T[];
+    /** A further visible item exists after `items`. */
+    readonly hasMore: boolean;
+    /** Source cursor for the next batch (pass back as `after`). */
+    readonly next: number;
+}
+/**
+ * A listing's batch size from its config: `config[limitKey]` floored and clamped into
+ * `[1, LISTING_BATCH_MAX]`, else `fallback` when the key is absent or not a positive finite number.
+ * @complexity O(1).
+ */
+export declare function parseListingBatchSize({ config }: {
+    config: Readonly<Record<string, unknown>>;
+}, { limitKey, fallback }?: {
+    limitKey?: string;
+    fallback?: number;
+}): number;
+/**
+ * One batch of up to `size` visible items starting at source cursor `after`. Reads `size + 1` rows a
+ * round (the extra row answers `hasMore` without a COUNT), at most {@link LISTING_SCAN_ROUNDS}
+ * rounds, so a run of hidden rows can shorten a batch but never make it unbounded.
+ * @complexity O(rounds) source reads of `size + 1` rows each, plus O(rows) `isVisible` calls.
+ */
+export declare function readListingBatch<T>({ source, after, size }: {
+    source: ListingSource<T>;
+    after: number;
+    size: number;
+}, { isVisible }?: {
+    isVisible?: (item: T) => boolean;
+}): Promise<ListingBatch<T>>;
+/** An in-memory {@link ListingSource} over an already-ordered array. @complexity O(limit). */
+export declare function arrayListingSource<T>({ rows }: {
+    rows: readonly T[];
+}, _optional?: Record<string, never>): ListingSource<T>;
+//# sourceMappingURL=batch.d.ts.map

package/dist/listing/batch.js

@@ -0,0 +1,57 @@
+/**
+ * "See more" listing batches: the one read rule every progressive listing (posts, collections, a
+ * future JSON endpoint) shares. `after`/`next` count SOURCE rows already consumed, not visible ones,
+ * so visibility (member access included) is applied before items are taken and a hidden row is
+ * never counted twice or shown out of order.
+ */
+/** Batch size a see-more listing uses when its config names none. */
+export const LISTING_BATCH_DEFAULT = 12;
+/** Ceiling on one batch, so neither an absent nor an adversarial config turns a listing into a scan. */
+export const LISTING_BATCH_MAX = 24;
+/** Ceiling on the source cursor: OFFSET cost is O(after), so a forged huge cursor is refused. */
+export const LISTING_AFTER_MAX = 100_000;
+/** Scan rounds before a batch is returned short; `hasMore` stays correct either way. */
+const LISTING_SCAN_ROUNDS = 4;
+/**
+ * A listing's batch size from its config: `config[limitKey]` floored and clamped into
+ * `[1, LISTING_BATCH_MAX]`, else `fallback` when the key is absent or not a positive finite number.
+ * @complexity O(1).
+ */
+export function parseListingBatchSize({ config }, { limitKey = 'limit', fallback = LISTING_BATCH_DEFAULT } = {}) {
+    const raw = config[limitKey];
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0)
+        return fallback;
+    return Math.max(1, Math.min(Math.floor(raw), LISTING_BATCH_MAX));
+}
+/**
+ * One batch of up to `size` visible items starting at source cursor `after`. Reads `size + 1` rows a
+ * round (the extra row answers `hasMore` without a COUNT), at most {@link LISTING_SCAN_ROUNDS}
+ * rounds, so a run of hidden rows can shorten a batch but never make it unbounded.
+ * @complexity O(rounds) source reads of `size + 1` rows each, plus O(rows) `isVisible` calls.
+ */
+export async function readListingBatch({ source, after, size }, { isVisible = () => true } = {}) {
+    const items = [];
+    let cursor = Math.max(0, Math.min(Math.floor(after), LISTING_AFTER_MAX));
+    for (let round = 0; round < LISTING_SCAN_ROUNDS; round += 1) {
+        const rows = await source({ offset: cursor, limit: size + 1 });
+        for (const row of rows) {
+            if (!isVisible(row)) {
+                cursor += 1;
+                continue;
+            }
+            // A visible row past a full batch only proves there is more; it stays unconsumed.
+            if (items.length === size)
+                return { items, hasMore: true, next: cursor };
+            items.push(row);
+            cursor += 1;
+        }
+        if (rows.length < size + 1)
+            return { items, hasMore: false, next: cursor };
+    }
+    return { items, hasMore: true, next: cursor };
+}
+/** An in-memory {@link ListingSource} over an already-ordered array. @complexity O(limit). */
+export function arrayListingSource({ rows }, _optional = {}) {
+    return async ({ offset, limit }) => rows.slice(offset, offset + limit);
+}
+//# sourceMappingURL=batch.js.map

package/dist/listing/html.d.ts

@@ -0,0 +1,72 @@
+/**
+ * String-level markup for see-more listings, so no HTML parser is needed:
+ * - the author marks a listing container with `data-jini-see-more`; {@link assignListingKeys} turns
+ *   that into `data-jini-listing="<key>"` (1-based, document order) before the listing renders;
+ * - the items sit between `<!--jini-listing:<key>-->` sentinels ({@link wrapListingItems}), which is
+ *   what {@link extractListingBatch} slices a batch response out of;
+ * - the button is a `<button>` carrying the next batch URL in `data-jini-more-href`
+ *   ({@link renderListingMore}), `hidden` until the inline script runs, so with no JS it is simply
+ *   absent (a batch URL alone is a bare fragment, so a plain link adds nothing for no-JS readers);
+ * - a listing that carries a `<template data-jini-card>` card ({@link extractListingCardTemplate})
+ *   loads its next batches as JSON (`.json` batch URLs) and the script fills a copy of the card per
+ *   item; without one it keeps loading server-rendered HTML batches.
+ */
+export declare const LISTING_SEE_MORE_ATTRIBUTE = "data-jini-see-more";
+/** Rewrites each `data-jini-see-more` attribute to `data-jini-listing="<key>"` in document order;
+ *  past {@link LISTING_KEY_MAX} the attribute is dropped and the listing renders plain. @complexity O(n). */
+export declare function assignListingKeys({ html }: {
+    html: string;
+}, _optional?: Record<string, never>): string;
+/** The listing key an element's attribute string carries, if any. @complexity O(n) over `attrs`. */
+export declare function listingKeyOfAttributes({ attrs }: {
+    attrs: string;
+}, _optional?: Record<string, never>): number | undefined;
+/** `items` between the sentinels {@link extractListingBatch} slices on. @complexity O(n). */
+export declare function wrapListingItems({ key, items }: {
+    key: number;
+    items: string;
+}, _optional?: Record<string, never>): string;
+/** The see-more button for `key`'s listing, carrying its next batch URL; the script shows
+ *  `loadingLabel` (disabled) while a batch is fetched. @complexity O(n) over `href`. */
+export declare function renderListingMore({ key, href }: {
+    key: number;
+    href: string;
+}, { label, loadingLabel }?: {
+    label?: string;
+    loadingLabel?: string;
+}): string;
+/** Adds the one inline see-more script before `</body>` when the page carries a see-more button and
+ *  does not already have the script. @complexity O(n). */
+export declare function injectListingScript({ html }: {
+    html: string;
+}, _optional?: Record<string, never>): string;
+/** `key`'s rendered items and next-batch href, or `undefined` when `html` has no such listing. @complexity O(n). */
+export declare function extractListingBatch({ html, key }: {
+    html: string;
+    key: number;
+}, _optional?: Record<string, never>): {
+    items: string;
+    moreHref?: string;
+} | undefined;
+/** The document a batch URL serves: the items plus the next button, or none on the last batch. @complexity O(n). */
+export declare function renderListingBatchDocument({ key, items, moreHref }: {
+    key: number;
+    items: string;
+    moreHref?: string;
+}, _optional?: Record<string, never>): string;
+/** Every see-more button's batch URL in `html`, for a static exporter to follow. @complexity O(n). */
+export declare function extractListingMoreHrefs({ html }: {
+    html: string;
+}, _optional?: Record<string, never>): readonly string[];
+/** The first `<template data-jini-card>…</template>` element in a listing's authored markup, whole,
+ *  or `undefined` when the listing has no client-side card. @complexity O(n). */
+export declare function extractListingCardTemplate({ html }: {
+    html: string;
+}, _optional?: Record<string, never>): string | undefined;
+/** The next `.json` batch URL a JSON batch at `path` points to, for a static exporter to follow, or
+ *  `undefined` after the last batch or for a body that is not a JSON batch. @complexity O(n). */
+export declare function listingJsonNextPath({ path, body }: {
+    path: string;
+    body: string;
+}, _optional?: Record<string, never>): string | undefined;
+//# sourceMappingURL=html.d.ts.map

package/dist/listing/html.js

@@ -0,0 +1,109 @@
+import { LISTING_KEY_MAX, listingBatchPath, parseListingBatchPath } from './paths.js';
+import { LISTING_SEE_MORE_SCRIPT } from './see-more-script.js';
+/**
+ * String-level markup for see-more listings, so no HTML parser is needed:
+ * - the author marks a listing container with `data-jini-see-more`; {@link assignListingKeys} turns
+ *   that into `data-jini-listing="<key>"` (1-based, document order) before the listing renders;
+ * - the items sit between `<!--jini-listing:<key>-->` sentinels ({@link wrapListingItems}), which is
+ *   what {@link extractListingBatch} slices a batch response out of;
+ * - the button is a `<button>` carrying the next batch URL in `data-jini-more-href`
+ *   ({@link renderListingMore}), `hidden` until the inline script runs, so with no JS it is simply
+ *   absent (a batch URL alone is a bare fragment, so a plain link adds nothing for no-JS readers);
+ * - a listing that carries a `<template data-jini-card>` card ({@link extractListingCardTemplate})
+ *   loads its next batches as JSON (`.json` batch URLs) and the script fills a copy of the card per
+ *   item; without one it keeps loading server-rendered HTML batches.
+ */
+export const LISTING_SEE_MORE_ATTRIBUTE = 'data-jini-see-more';
+const SEE_MORE_IN_OPEN_TAG = /(<[a-z][a-z0-9-]*\b[^<>]*?\s)data-jini-see-more(?:=(?:""|''))?(?=[\s/>])/gi;
+const LISTING_KEY_ATTRIBUTE = /(?:^|\s)data-jini-listing="(\d+)"/;
+const SCRIPT_MARKER = 'data-jini-see-more-script';
+function escapeAttribute(value) {
+    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function decodeAttribute(value) {
+    return value.replace(/&quot;/g, '"').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+}
+/** Rewrites each `data-jini-see-more` attribute to `data-jini-listing="<key>"` in document order;
+ *  past {@link LISTING_KEY_MAX} the attribute is dropped and the listing renders plain. @complexity O(n). */
+export function assignListingKeys({ html }, _optional = {}) {
+    let key = 0;
+    return html.replace(SEE_MORE_IN_OPEN_TAG, (_whole, before) => {
+        key += 1;
+        return key > LISTING_KEY_MAX ? before.trimEnd() : `${before}data-jini-listing="${key}"`;
+    });
+}
+/** The listing key an element's attribute string carries, if any. @complexity O(n) over `attrs`. */
+export function listingKeyOfAttributes({ attrs }, _optional = {}) {
+    const match = LISTING_KEY_ATTRIBUTE.exec(attrs);
+    return match ? Number(match[1]) : undefined;
+}
+/** `items` between the sentinels {@link extractListingBatch} slices on. @complexity O(n). */
+export function wrapListingItems({ key, items }, _optional = {}) {
+    return `<!--jini-listing:${key}-->${items}<!--/jini-listing:${key}-->`;
+}
+/** The see-more button for `key`'s listing, carrying its next batch URL; the script shows
+ *  `loadingLabel` (disabled) while a batch is fetched. @complexity O(n) over `href`. */
+export function renderListingMore({ key, href }, { label = 'See more', loadingLabel = 'Loading…' } = {}) {
+    return `<button type="button" class="jini-see-more" data-jini-more="${key}" data-jini-more-href="${escapeAttribute(href)}" data-jini-loading="${escapeAttribute(loadingLabel)}" hidden>${escapeAttribute(label)}</button>`;
+}
+/** Adds the one inline see-more script before `</body>` when the page carries a see-more button and
+ *  does not already have the script. @complexity O(n). */
+export function injectListingScript({ html }, _optional = {}) {
+    if (!html.includes('data-jini-more=') || html.includes(SCRIPT_MARKER))
+        return html;
+    const script = `<script ${SCRIPT_MARKER}>${LISTING_SEE_MORE_SCRIPT}</script>`;
+    const bodyClose = html.lastIndexOf('</body>');
+    return bodyClose === -1 ? html + script : html.slice(0, bodyClose) + script + html.slice(bodyClose);
+}
+function moreHrefsIn(html, key) {
+    const hrefs = [];
+    for (const [tag] of html.matchAll(/<button\b[^<>]*\bdata-jini-more="(\d+)"[^<>]*>/g)) {
+        if (key !== undefined && !tag.includes(`data-jini-more="${key}"`))
+            continue;
+        const href = /\bdata-jini-more-href="([^"]*)"/.exec(tag)?.[1];
+        if (href !== undefined)
+            hrefs.push(decodeAttribute(href));
+    }
+    return hrefs;
+}
+/** `key`'s rendered items and next-batch href, or `undefined` when `html` has no such listing. @complexity O(n). */
+export function extractListingBatch({ html, key }, _optional = {}) {
+    const open = `<!--jini-listing:${key}-->`;
+    const start = html.indexOf(open);
+    const end = start === -1 ? -1 : html.indexOf(`<!--/jini-listing:${key}-->`, start);
+    if (end === -1)
+        return undefined;
+    const moreHref = moreHrefsIn(html.slice(end), key)[0];
+    return { items: html.slice(start + open.length, end), ...(moreHref !== undefined ? { moreHref } : {}) };
+}
+/** The document a batch URL serves: the items plus the next button, or none on the last batch. @complexity O(n). */
+export function renderListingBatchDocument({ key, items, moreHref }, _optional = {}) {
+    const more = moreHref === undefined ? '' : renderListingMore({ key, href: moreHref }).replace(' hidden>', '>');
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="robots" content="noindex"></head><body><div data-jini-listing-batch="${key}">${items}</div>${more}</body></html>`;
+}
+/** Every see-more button's batch URL in `html`, for a static exporter to follow. @complexity O(n). */
+export function extractListingMoreHrefs({ html }, _optional = {}) {
+    return moreHrefsIn(html);
+}
+const CARD_TEMPLATE = /<template\b[^<>]*\sdata-jini-card(?:=(?:""|''))?[\s>][\s\S]*?<\/template>/i;
+/** The first `<template data-jini-card>…</template>` element in a listing's authored markup, whole,
+ *  or `undefined` when the listing has no client-side card. @complexity O(n). */
+export function extractListingCardTemplate({ html }, _optional = {}) {
+    return CARD_TEMPLATE.exec(html)?.[0];
+}
+/** The next `.json` batch URL a JSON batch at `path` points to, for a static exporter to follow, or
+ *  `undefined` after the last batch or for a body that is not a JSON batch. @complexity O(n). */
+export function listingJsonNextPath({ path, body }, _optional = {}) {
+    const request = parseListingBatchPath({ path });
+    if (request?.format !== 'json')
+        return undefined;
+    let nextCursor;
+    try {
+        nextCursor = JSON.parse(body).nextCursor;
+    }
+    catch {
+        return undefined;
+    }
+    return typeof nextCursor === 'number' && Number.isInteger(nextCursor) && nextCursor > request.after ? listingBatchPath({ ...request, after: nextCursor }) : undefined;
+}
+//# sourceMappingURL=html.js.map

package/dist/listing/index.d.ts

@@ -0,0 +1,5 @@
+export * from './batch.js';
+export * from './paths.js';
+export * from './html.js';
+export * from './see-more-script.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/listing/index.js

@@ -0,0 +1,5 @@
+export * from './batch.js';
+export * from './paths.js';
+export * from './html.js';
+export * from './see-more-script.js';
+//# sourceMappingURL=index.js.map

package/dist/listing/paths.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Batch URLs: `<pagePath>/_more/<key>/<after>` (home: `/_more/1/12`). `_` is not a legal slug, so a
+ * batch URL can never collide with content, and it is a plain directory route, so a static export
+ * writes `.../<after>/index.html` that every static host serves unchanged. The JSON form of the same
+ * batch is `<pagePath>/_more/<key>/<after>.json`, exported as that file.
+ */
+/** Most see-more listings one page may carry; keys are their 1-based document-order ordinals. */
+export declare const LISTING_KEY_MAX = 10;
+export interface ListingBatchRequest {
+    /** The listing page's own path (`/` for home). */
+    readonly pagePath: string;
+    readonly key: number;
+    readonly after: number;
+    /** `'json'` for the `.json` form ({@link ListingJsonPage}); absent for the HTML batch. */
+    readonly format?: 'json';
+}
+/** A JSON batch's body: one page of a listing's public items plus the cursor for the next, or `null` after the last. */
+export interface ListingJsonPage<T> {
+    readonly items: readonly T[];
+    readonly nextCursor: number | null;
+}
+/** The batch URL for `key`'s listing on `pagePath`, starting at source cursor `after`. @complexity O(n) over `pagePath`. */
+export declare function listingBatchPath({ pagePath, key, after, format }: ListingBatchRequest, _optional?: Record<string, never>): string;
+/**
+ * The batch request a URL path names, or `undefined` when it is not a well-formed batch URL: a bad
+ * key or cursor, a `.`/`..` segment, or an `admin`/`api` page are refused, never normalized.
+ * @complexity O(n) over `path`.
+ */
+export declare function parseListingBatchPath({ path }: {
+    path: string;
+}, _optional?: Record<string, never>): ListingBatchRequest | undefined;
+//# sourceMappingURL=paths.d.ts.map

package/dist/listing/paths.js

@@ -0,0 +1,37 @@
+import { LISTING_AFTER_MAX } from './batch.js';
+/**
+ * Batch URLs: `<pagePath>/_more/<key>/<after>` (home: `/_more/1/12`). `_` is not a legal slug, so a
+ * batch URL can never collide with content, and it is a plain directory route, so a static export
+ * writes `.../<after>/index.html` that every static host serves unchanged. The JSON form of the same
+ * batch is `<pagePath>/_more/<key>/<after>.json`, exported as that file.
+ */
+/** Most see-more listings one page may carry; keys are their 1-based document-order ordinals. */
+export const LISTING_KEY_MAX = 10;
+const BATCH_PATH = /^((?:\/[^/]+)*)\/_more\/([1-9]\d?)\/(\d{1,6})(?:(\.json)|\/?)$/;
+const RESERVED_FIRST_SEGMENTS = new Set(['admin', 'api']);
+/** The batch URL for `key`'s listing on `pagePath`, starting at source cursor `after`. @complexity O(n) over `pagePath`. */
+export function listingBatchPath({ pagePath, key, after, format }, _optional = {}) {
+    return `${pagePath.replace(/\/+$/, '')}/_more/${key}/${after}${format === 'json' ? '.json' : ''}`;
+}
+/**
+ * The batch request a URL path names, or `undefined` when it is not a well-formed batch URL: a bad
+ * key or cursor, a `.`/`..` segment, or an `admin`/`api` page are refused, never normalized.
+ * @complexity O(n) over `path`.
+ */
+export function parseListingBatchPath({ path }, _optional = {}) {
+    const match = BATCH_PATH.exec(path);
+    if (!match)
+        return undefined;
+    const [, page = '', rawKey = '', rawAfter = '', json] = match;
+    const segments = page.split('/').filter(Boolean);
+    if (segments.some((segment) => segment === '.' || segment === '..' || segment === '_more'))
+        return undefined;
+    if (segments[0] !== undefined && RESERVED_FIRST_SEGMENTS.has(segments[0]))
+        return undefined;
+    const key = Number(rawKey);
+    const after = Number(rawAfter);
+    if (key > LISTING_KEY_MAX || after > LISTING_AFTER_MAX)
+        return undefined;
+    return { pagePath: page === '' ? '/' : page, key, after, ...(json ? { format: 'json' } : {}) };
+}
+//# sourceMappingURL=paths.js.map

package/dist/listing/see-more-script.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The inline script behind every see-more button ({@link injectListingScript} adds it once per page).
+ * It reveals the `hidden` buttons, then on click fetches the batch URL (`data-jini-more-href`),
+ * appends the batch's items to the `[data-jini-listing=key]` container (before the button when the
+ * button sits inside that container, so it stays below the cards) and swaps in the next URL, or
+ * removes the button after the last batch. While a fetch is in flight the button is disabled,
+ * `aria-busy`, and shows its `data-jini-loading` label; a failed fetch restores it.
+ *
+ * A `.json` batch URL (the listing has a `<template data-jini-card>`) is read as a
+ * {@link ListingJsonPage}: each item fills a copy of that card and the next URL is built from
+ * `nextCursor`. Bindings: `data-field="path"` sets `textContent`; `data-field-<attr>="path"` sets one of
+ * href/src/alt/title/datetime/width/height, and href/src only when relative or http(s). A text or
+ * href/src binding with no value removes its element. Data is never parsed as HTML.
+ */
+export declare const LISTING_SEE_MORE_SCRIPT = "(function(){\n  var ATTRS={href:1,src:1,alt:1,title:1,datetime:1,width:1,height:1};\n  function value(item,path){var v=item;var keys=path.split('.');for(var i=0;i<keys.length&&v!=null;i++)v=Object.prototype.hasOwnProperty.call(v,keys[i])?v[keys[i]]:undefined;if(Array.isArray(v))v=v.join(', ');return v==null||typeof v==='object'?'':String(v);}\n  function fill(root,item){\n  var els=root.querySelectorAll('*');\n  for(var i=0;i<els.length;i++){var el=els[i];var drop=false;\n  for(var a=el.attributes.length-1;a>=0;a--){var name=el.attributes[a].name;if(name!=='data-field'&&name.indexOf('data-field-')!==0)continue;\n  var v=value(item,el.attributes[a].value);el.removeAttribute(name);\n  if(name==='data-field'){if(v==='')drop=true;else el.textContent=v;continue;}\n  var attr=name.slice(11);if(!ATTRS[attr])continue;\n  var link=attr==='href'||attr==='src';\n  if(link&&/^\\s*[a-z][a-z0-9+.-]*:/i.test(v)&&!/^\\s*https?:/i.test(v))v='';\n  if(v!=='')el.setAttribute(attr,v);else if(link)drop=true;}\n  if(drop&&el.parentNode)el.parentNode.removeChild(el);}\n  return root;}\n  var buttons=document.querySelectorAll('button[data-jini-more]');\n  for(var i=0;i<buttons.length;i++)buttons[i].hidden=false;\n  document.addEventListener('click',function(e){\n  var b=e.target&&e.target.closest?e.target.closest('button[data-jini-more]'):null;\n  if(!b||b.disabled)return;\n  var list=document.querySelector('[data-jini-listing=\"'+b.getAttribute('data-jini-more')+'\"]');\n  if(!list||!window.fetch||!window.DOMParser)return;\n  var label=b.textContent;\n  function idle(){b.disabled=false;b.removeAttribute('aria-busy');b.textContent=label;}\n  b.disabled=true;b.setAttribute('aria-busy','true');b.textContent=b.getAttribute('data-jini-loading')||label;\n  var href=b.getAttribute('data-jini-more-href')||'';\n  var json=/\\.json$/.test(href.split(/[?#]/)[0]);\n  var tpl=json?list.querySelector('template[data-jini-card]'):null;\n  if(json&&!tpl)return idle();\n  fetch(href,{credentials:'same-origin'}).then(function(r){if(!r.ok)throw new Error(String(r.status));return r.text();}).then(function(text){\n  var anchor=list.contains(b)?b:null;\n  if(json){\n  var data=JSON.parse(text);\n  if(!data||!Array.isArray(data.items))throw new Error('no batch');\n  for(var n=0;n<data.items.length;n++)list.insertBefore(fill(tpl.content.cloneNode(true),data.items[n]),anchor);\n  if(typeof data.nextCursor==='number'){b.setAttribute('data-jini-more-href',href.replace(/\\/\\d+\\.json/,'/'+data.nextCursor+'.json'));idle();}else{b.parentNode.removeChild(b);}\n  return;\n  }\n  var doc=new DOMParser().parseFromString(text,'text/html');\n  var batch=doc.querySelector('[data-jini-listing-batch]');\n  if(!batch)throw new Error('no batch');\n  while(batch.firstChild)list.insertBefore(document.adoptNode(batch.firstChild),anchor);\n  var next=doc.querySelector('button[data-jini-more]');\n  if(next){b.setAttribute('data-jini-more-href',next.getAttribute('data-jini-more-href'));idle();}else{b.parentNode.removeChild(b);}\n  }).catch(idle);\n  });\n  })();";
+//# sourceMappingURL=see-more-script.d.ts.map

package/dist/listing/see-more-script.js

@@ -0,0 +1,62 @@
+/**
+ * The inline script behind every see-more button ({@link injectListingScript} adds it once per page).
+ * It reveals the `hidden` buttons, then on click fetches the batch URL (`data-jini-more-href`),
+ * appends the batch's items to the `[data-jini-listing=key]` container (before the button when the
+ * button sits inside that container, so it stays below the cards) and swaps in the next URL, or
+ * removes the button after the last batch. While a fetch is in flight the button is disabled,
+ * `aria-busy`, and shows its `data-jini-loading` label; a failed fetch restores it.
+ *
+ * A `.json` batch URL (the listing has a `<template data-jini-card>`) is read as a
+ * {@link ListingJsonPage}: each item fills a copy of that card and the next URL is built from
+ * `nextCursor`. Bindings: `data-field="path"` sets `textContent`; `data-field-<attr>="path"` sets one of
+ * href/src/alt/title/datetime/width/height, and href/src only when relative or http(s). A text or
+ * href/src binding with no value removes its element. Data is never parsed as HTML.
+ */
+export const LISTING_SEE_MORE_SCRIPT = `(function(){
+  var ATTRS={href:1,src:1,alt:1,title:1,datetime:1,width:1,height:1};
+  function value(item,path){var v=item;var keys=path.split('.');for(var i=0;i<keys.length&&v!=null;i++)v=Object.prototype.hasOwnProperty.call(v,keys[i])?v[keys[i]]:undefined;if(Array.isArray(v))v=v.join(', ');return v==null||typeof v==='object'?'':String(v);}
+  function fill(root,item){
+  var els=root.querySelectorAll('*');
+  for(var i=0;i<els.length;i++){var el=els[i];var drop=false;
+  for(var a=el.attributes.length-1;a>=0;a--){var name=el.attributes[a].name;if(name!=='data-field'&&name.indexOf('data-field-')!==0)continue;
+  var v=value(item,el.attributes[a].value);el.removeAttribute(name);
+  if(name==='data-field'){if(v==='')drop=true;else el.textContent=v;continue;}
+  var attr=name.slice(11);if(!ATTRS[attr])continue;
+  var link=attr==='href'||attr==='src';
+  if(link&&/^\\s*[a-z][a-z0-9+.-]*:/i.test(v)&&!/^\\s*https?:/i.test(v))v='';
+  if(v!=='')el.setAttribute(attr,v);else if(link)drop=true;}
+  if(drop&&el.parentNode)el.parentNode.removeChild(el);}
+  return root;}
+  var buttons=document.querySelectorAll('button[data-jini-more]');
+  for(var i=0;i<buttons.length;i++)buttons[i].hidden=false;
+  document.addEventListener('click',function(e){
+  var b=e.target&&e.target.closest?e.target.closest('button[data-jini-more]'):null;
+  if(!b||b.disabled)return;
+  var list=document.querySelector('[data-jini-listing="'+b.getAttribute('data-jini-more')+'"]');
+  if(!list||!window.fetch||!window.DOMParser)return;
+  var label=b.textContent;
+  function idle(){b.disabled=false;b.removeAttribute('aria-busy');b.textContent=label;}
+  b.disabled=true;b.setAttribute('aria-busy','true');b.textContent=b.getAttribute('data-jini-loading')||label;
+  var href=b.getAttribute('data-jini-more-href')||'';
+  var json=/\\.json$/.test(href.split(/[?#]/)[0]);
+  var tpl=json?list.querySelector('template[data-jini-card]'):null;
+  if(json&&!tpl)return idle();
+  fetch(href,{credentials:'same-origin'}).then(function(r){if(!r.ok)throw new Error(String(r.status));return r.text();}).then(function(text){
+  var anchor=list.contains(b)?b:null;
+  if(json){
+  var data=JSON.parse(text);
+  if(!data||!Array.isArray(data.items))throw new Error('no batch');
+  for(var n=0;n<data.items.length;n++)list.insertBefore(fill(tpl.content.cloneNode(true),data.items[n]),anchor);
+  if(typeof data.nextCursor==='number'){b.setAttribute('data-jini-more-href',href.replace(/\\/\\d+\\.json/,'/'+data.nextCursor+'.json'));idle();}else{b.parentNode.removeChild(b);}
+  return;
+  }
+  var doc=new DOMParser().parseFromString(text,'text/html');
+  var batch=doc.querySelector('[data-jini-listing-batch]');
+  if(!batch)throw new Error('no batch');
+  while(batch.firstChild)list.insertBefore(document.adoptNode(batch.firstChild),anchor);
+  var next=doc.querySelector('button[data-jini-more]');
+  if(next){b.setAttribute('data-jini-more-href',next.getAttribute('data-jini-more-href'));idle();}else{b.parentNode.removeChild(b);}
+  }).catch(idle);
+  });
+  })();`;
+//# sourceMappingURL=see-more-script.js.map

package/dist/media/content-type-sniffer.d.ts

@@ -31,7 +31,7 @@
  */
 /** Recognized outputs. Anything not covered here falls back to the network's
  * default-safe unknown-binary label — see {@link sniffContentType}'s doc. */
-export type SniffedContentType = "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/avif" | "video/mp4" | "video/webm" | "text/html" | "image/svg+xml" | "application/octet-stream";
+export type SniffedContentType = "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/avif" | "video/mp4" | "video/webm" | "audio/wav" | "audio/mpeg" | "audio/flac" | "audio/mp4" | "text/html" | "image/svg+xml" | "application/octet-stream";
 /**
  * Identifies a media type from `bytes`' leading magic bytes. Allowlist-shaped: only the formats
  * named in {@link SniffedContentType} are ever returned as something other than

package/dist/media/content-type-sniffer.js

@@ -175,10 +175,25 @@ export function sniffContentType({ bytes }, _optional = {}) {
     // otherwise claim every AVIF as video/mp4 (the 2026-09-06 regression).
     if (isAvif(bytes))
         return "image/avif";
+    // Audio support (owner-approved mediawidget, 2026-10-10/11) shares the original-byte
+    // path. Distinguish explicit M4A brands before the existing ISO-BMFF video fallback.
+    if (isIsoBmffFtyp(bytes) && asciiEqualAt(bytes, 8, "M4A "))
+        return "audio/mp4";
     if (isIsoBmffFtyp(bytes))
         return "video/mp4";
     if (isWebm(bytes))
         return "video/webm";
+    if (asciiEqualAt(bytes, 0, "RIFF") && asciiEqualAt(bytes, 8, "WAVE"))
+        return "audio/wav";
+    if (asciiEqualAt(bytes, 0, "fLaC"))
+        return "audio/flac";
+    if (asciiEqualAt(bytes, 0, "ID3"))
+        return "audio/mpeg";
+    // Untagged MPEG audio: sync bits plus non-reserved version, layer, bitrate and sample rate.
+    if (bytes.length >= 4 && bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0 &&
+        (bytes[1] & 0x18) !== 0x08 && (bytes[1] & 0x06) !== 0 &&
+        (bytes[2] & 0xf0) !== 0 && (bytes[2] & 0xf0) !== 0xf0 && (bytes[2] & 0x0c) !== 0x0c)
+        return "audio/mpeg";
     const text = leadingText(bytes);
     if (isHtmlLike(text))
         return "text/html";