@segnavia/html 0.21.0 → 0.23.0

package/dist/bindings.d.ts

@@ -6,6 +6,7 @@ export interface FillOptions extends Pick<SanitizeOptions, 'linkOrigins'> {
   prefix: string;
   data: Record<string, unknown>;
   unavailable?: Iterable<string>;
+  preserveUnavailable?: boolean;
 }
 export interface Filled {
   html: string;

package/dist/bindings.js

@@ -96,6 +96,7 @@ function fill(html, options) {
 		const path = take(element, names.value);
 		if (path === void 0) return;
 		const value = resolve(path, stack);
+		if (value === void 0 && options.preserveUnavailable) return;
 		element.children = [];
 		if (typeof value === "string" || typeof value === "number" && Number.isFinite(value)) {
 			const text = new Text(String(value));
@@ -106,10 +107,12 @@ function fill(html, options) {
 		} else if (value !== void 0) unavailable.add(path);
 	};
 	const applyUrls = (element, stack) => {
+		const preserves = (value) => value === void 0 && options.preserveUnavailable;
 		for (const attribute of ["href", "src"]) {
 			const path = take(element, names[attribute]);
 			if (path === void 0) continue;
 			const value = resolve(path, stack);
+			if (preserves(value)) continue;
 			if (typeof value === "string" && (attribute === "href" ? safeHref(value, origins) : /^data:image\//i.test(value))) element.attribs[attribute] = value;
 			else {
 				delete element.attribs[attribute];

package/dist/index.d.ts

@@ -2,9 +2,12 @@ import { REFUSED_ELEMENTS, SanitizeOptions, findActiveContent, sanitize } from "
 import { BINDINGS, FillOptions, Filled, bindingNames, fill, hasBindings } from "./bindings.js";
 import { BookDocument, BookDocumentOptions, BookHeading, BookPrintPart, BookSectionInfo, bookPrintPart } from "./book/types.js";
 import { bookDocument } from "./book/book-document.js";
+import { SlotFillEntry, SlotFillRefusal, SlotFillsConflictError, SlotFillsRefusedError, SlotPrintOptions, assertSingleSlotCopy, assertSlotPrintOptions, collectSlotPrintCopies, isSlotCopyRefusal, slotFillCopyId, slotFillsConflict } from "./slot-print.js";
+import { RequiredSlotsRefusedError, UnmeasuredSlotsRefusedError, mergeSlotFitResults, requiredSlotRefusal, unmeasuredSlotRefusal } from "./slot-policy.js";
+import { MAX_SLOT_DECLARATIONS, PreparedSlots, SlotFillRefusedError, hasSlotWork, prepareSlotCollection, prepareSlots, slotFillRefusal } from "./slots.js";
 //#region src/index.d.ts
 export type HtmlKind = 'plain' | 'live-data' | 'scripted' | 'refused';
 export declare function classify(html: string, prefix: string): HtmlKind;
 export declare function searchText(html: string): string;
 //#endregion
-export { BINDINGS, type BookDocument, type BookDocumentOptions, type BookHeading, type BookPrintPart, type BookSectionInfo, type FillOptions, type Filled, REFUSED_ELEMENTS, type SanitizeOptions, bindingNames, bookDocument, bookPrintPart, fill, findActiveContent, hasBindings, sanitize };
+export { BINDINGS, type BookDocument, type BookDocumentOptions, type BookHeading, type BookPrintPart, type BookSectionInfo, type FillOptions, type Filled, MAX_SLOT_DECLARATIONS, type PreparedSlots, REFUSED_ELEMENTS, RequiredSlotsRefusedError, type SanitizeOptions, type SlotFillEntry, type SlotFillRefusal, SlotFillRefusedError, SlotFillsConflictError, SlotFillsRefusedError, type SlotPrintOptions, UnmeasuredSlotsRefusedError, assertSingleSlotCopy, assertSlotPrintOptions, bindingNames, bookDocument, bookPrintPart, collectSlotPrintCopies, fill, findActiveContent, hasBindings, hasSlotWork, isSlotCopyRefusal, mergeSlotFitResults, prepareSlotCollection, prepareSlots, requiredSlotRefusal, sanitize, slotFillCopyId, slotFillRefusal, slotFillsConflict, unmeasuredSlotRefusal };

package/dist/index.js

@@ -2,6 +2,9 @@ import { REFUSED_ELEMENTS, elements, findActiveContent, parse, sanitize } from "
 import { BINDINGS, bindingNames, fill, hasBindings } from "./bindings.js";
 import { bookPrintPart } from "./book/types.js";
 import { bookDocument } from "./book/book-document.js";
+import { RequiredSlotsRefusedError, UnmeasuredSlotsRefusedError, mergeSlotFitResults, requiredSlotRefusal, unmeasuredSlotRefusal } from "./slot-policy.js";
+import { MAX_SLOT_DECLARATIONS, SlotFillRefusedError, hasSlotWork, prepareSlotCollection, prepareSlots, slotFillRefusal } from "./slots.js";
+import { SlotFillsConflictError, SlotFillsRefusedError, assertSingleSlotCopy, assertSlotPrintOptions, collectSlotPrintCopies, isSlotCopyRefusal, slotFillCopyId, slotFillsConflict } from "./slot-print.js";
 //#region src/index.ts
 function classify(html, prefix) {
 	const scripted = elements(parse(html).children).some((element) => element.name.toLowerCase() === "script");
@@ -14,4 +17,4 @@ function searchText(html) {
 	return html.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, " ").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
 }
 //#endregion
-export { BINDINGS, REFUSED_ELEMENTS, bindingNames, bookDocument, bookPrintPart, classify, fill, findActiveContent, hasBindings, sanitize, searchText };
+export { BINDINGS, MAX_SLOT_DECLARATIONS, REFUSED_ELEMENTS, RequiredSlotsRefusedError, SlotFillRefusedError, SlotFillsConflictError, SlotFillsRefusedError, UnmeasuredSlotsRefusedError, assertSingleSlotCopy, assertSlotPrintOptions, bindingNames, bookDocument, bookPrintPart, classify, collectSlotPrintCopies, fill, findActiveContent, hasBindings, hasSlotWork, isSlotCopyRefusal, mergeSlotFitResults, prepareSlotCollection, prepareSlots, requiredSlotRefusal, sanitize, searchText, slotFillCopyId, slotFillRefusal, slotFillsConflict, unmeasuredSlotRefusal };

package/dist/qr.js

@@ -0,0 +1,39 @@
+import { Element } from "domhandler";
+import qrcode from "qrcode-generator";
+//#region src/qr.ts
+const QR_PAYLOAD_LIMIT = 4096;
+function qrPayload(value) {
+	try {
+		const url = new URL(value);
+		if (url.protocol !== "https:" || url.href.length > QR_PAYLOAD_LIMIT) return void 0;
+		const code = qrcode(0, "M");
+		code.addData(url.href);
+		code.make();
+		return url.href;
+	} catch {
+		return;
+	}
+}
+/** A QR code of the link at level M, drawn in currentColor with a four-module quiet zone. */
+function qrSvg(value) {
+	const code = qrcode(0, "M");
+	code.addData(qrPayload(value) ?? value);
+	code.make();
+	const modules = code.getModuleCount();
+	const children = [];
+	for (let row = 0; row < modules; row++) for (let column = 0; column < modules; column++) if (code.isDark(row, column)) children.push(new Element("rect", {
+		x: String(column + 4),
+		y: String(row + 4),
+		width: "1",
+		height: "1",
+		fill: "currentColor"
+	}));
+	return new Element("svg", {
+		viewBox: `0 0 ${modules + 8} ${modules + 8}`,
+		"shape-rendering": "crispEdges",
+		role: "img",
+		"aria-label": value
+	}, children);
+}
+//#endregion
+export { qrPayload, qrSvg };

package/dist/sanitize.js

@@ -48,7 +48,9 @@ const DATA_IMAGE = /^data:image\/(?:png|jpeg|gif|webp|svg\+xml)(?:[;,])/i;
 function parse(html) {
 	return parseDocument(html, {
 		lowerCaseAttributeNames: true,
-		recognizeSelfClosing: true
+		recognizeSelfClosing: true,
+		withStartIndices: true,
+		withEndIndices: true
 	});
 }
 function serialize(node) {

package/dist/slot-policy.d.ts

@@ -0,0 +1,27 @@
+import { SlotDeclaration, SlotReport, SlotState } from "@segnavia/format";
+//#region src/slot-policy.d.ts
+export declare class RequiredSlotsRefusedError extends Error {
+  readonly slots: ReadonlyArray<{
+    key: string;
+    state: SlotState;
+  }>;
+  constructor(slots: ReadonlyArray<{
+    key: string;
+    state: SlotState;
+  }>);
+}
+export declare class UnmeasuredSlotsRefusedError extends Error {
+  readonly keys: readonly string[];
+  constructor(slots: readonly string[]);
+}
+/** Returns the print/render refusal for required or overflowing declarations. */
+export declare function requiredSlotRefusal(declarations: readonly SlotDeclaration[], report: SlotReport): RequiredSlotsRefusedError | undefined;
+/**
+ * Refuses filled refuse-overflow slots that some frame marked but did not report before output. Counts are per key:
+ * frames that marked it, against fit reports received, so one frame's report cannot stand in for another's.
+ * A slot no frame binds has nothing to measure.
+ */
+export declare function unmeasuredSlotRefusal(declarations: readonly SlotDeclaration[], report: SlotReport, marked: ReadonlyMap<string, number>, measured: ReadonlyMap<string, number>): UnmeasuredSlotsRefusedError | undefined;
+/** Merges measured fit states into filled declared slots; any other state, and any undeclared key, is left as it was. */
+export declare function mergeSlotFitResults(declarations: readonly SlotDeclaration[], report: SlotReport, slots: Record<string, 'fit' | 'shrunk' | 'overflowed'>): SlotReport;
+//#endregion

package/dist/slot-policy.js

@@ -0,0 +1,61 @@
+//#region src/slot-policy.ts
+var RequiredSlotsRefusedError = class extends Error {
+	slots;
+	constructor(slots) {
+		super(`Output was refused because slots prevent printing: ${slots.map(({ key, state }) => `"${key}" (${state})`).join(", ")}. Fill required slots; for an overflowed refuse slot, shorten its value or change the slot's overflow.`);
+		this.name = "RequiredSlotsRefusedError";
+		this.slots = slots;
+	}
+};
+var UnmeasuredSlotsRefusedError = class extends Error {
+	keys;
+	constructor(slots) {
+		super(`Output was refused because overflow could not be measured for slots: ${slots.map((key) => `"${key}"`).join(", ")}. Ensure each filled slot frame becomes ready before the output deadline, or change the slot's overflow from 'refuse'.`);
+		this.name = "UnmeasuredSlotsRefusedError";
+		this.keys = slots;
+	}
+};
+/** Returns the print/render refusal for required or overflowing declarations. */
+function requiredSlotRefusal(declarations, report) {
+	const refused = declarations.flatMap((slot) => {
+		const state = report.slots[slot.key];
+		const required = slot.required && state !== "filled" && state !== "fit" && state !== "shrunk" && state !== void 0;
+		const overflow = slot.overflow === "refuse" && state === "overflowed";
+		return required || overflow ? [{
+			key: slot.key,
+			state
+		}] : [];
+	});
+	return refused.length === 0 ? void 0 : new RequiredSlotsRefusedError(refused);
+}
+/**
+* Refuses filled refuse-overflow slots that some frame marked but did not report before output. Counts are per key:
+* frames that marked it, against fit reports received, so one frame's report cannot stand in for another's.
+* A slot no frame binds has nothing to measure.
+*/
+function unmeasuredSlotRefusal(declarations, report, marked, measured) {
+	const unmeasured = declarations.flatMap((slot) => slot.overflow === "refuse" && report.slots[slot.key] !== "overflowed" && (measured.get(slot.key) ?? 0) < (marked.get(slot.key) ?? 0) ? [slot.key] : []);
+	return unmeasured.length === 0 ? void 0 : new UnmeasuredSlotsRefusedError(unmeasured);
+}
+/** Merges measured fit states into filled declared slots; any other state, and any undeclared key, is left as it was. */
+function mergeSlotFitResults(declarations, report, slots) {
+	const declared = new Set(declarations.map((slot) => slot.key));
+	const merged = { ...report.slots };
+	const rank = {
+		fit: 0,
+		shrunk: 1,
+		overflowed: 2
+	};
+	for (const [key, state] of Object.entries(slots)) {
+		if (!declared.has(key)) continue;
+		const previous = merged[key];
+		if (previous === "filled") merged[key] = state;
+		else if ((previous === "fit" || previous === "shrunk" || previous === "overflowed") && rank[state] > rank[previous]) merged[key] = state;
+	}
+	return {
+		...report,
+		slots: merged
+	};
+}
+//#endregion
+export { RequiredSlotsRefusedError, UnmeasuredSlotsRefusedError, mergeSlotFitResults, requiredSlotRefusal, unmeasuredSlotRefusal };

package/dist/slot-print.d.ts

@@ -0,0 +1,40 @@
+import { Fill, SlotsOptions } from "@segnavia/format";
+//#region src/slot-print.d.ts
+/** One copy of a print/PDF item: that copy's hand layer over its source layer. */
+export interface SlotFillEntry {
+  fill?: Fill;
+  source?: Fill;
+}
+export interface SlotPrintOptions extends SlotsOptions {
+  fills?: SlotFillEntry[];
+  /** When set, copies that would be refused are reported and omitted; the job still refuses if none remain. */
+  skipRefused?: boolean;
+}
+export declare class SlotFillsConflictError extends Error {
+  constructor();
+}
+export interface SlotFillRefusal {
+  index: number;
+  id: string;
+  slots: ReadonlyArray<{
+    key: string;
+    state: string;
+  }>;
+  error: Error;
+}
+export declare class SlotFillsRefusedError extends Error {
+  readonly entries: readonly SlotFillRefusal[];
+  constructor(entries: readonly SlotFillRefusal[]);
+}
+export declare function slotFillCopyId(entry: SlotFillEntry, index: number): string;
+export declare function slotFillsConflict(options: SlotPrintOptions | undefined): SlotFillsConflictError | undefined;
+export declare function assertSlotPrintOptions(options: SlotPrintOptions | undefined): void;
+/** Single-copy fill paths refuse `fills`; print and PDF jobs loop it themselves. */
+export declare function assertSingleSlotCopy(options: SlotsOptions | undefined): void;
+export declare function isSlotCopyRefusal(error: unknown): error is Error;
+/**
+ * Runs one print/PDF copy per `fills` entry, in order. Without `fills`, runs once with the given options.
+ * Host `report` is called once per entry, in entry order, including refused copies.
+ */
+export declare function collectSlotPrintCopies<T>(options: SlotPrintOptions | undefined, renderCopy: (copy: SlotsOptions) => Promise<T>): Promise<T[]>;
+//#endregion

package/dist/slot-print.js

@@ -0,0 +1,142 @@
+import { RequiredSlotsRefusedError, UnmeasuredSlotsRefusedError } from "./slot-policy.js";
+import { SlotFillRefusedError } from "./slots.js";
+//#region src/slot-print.ts
+var SlotFillsConflictError = class extends Error {
+	constructor() {
+		super("slots.fills cannot be given together with slots.fill or slots.source. Pass only fills, or only fill and source, to clear this refusal.");
+		this.name = "SlotFillsConflictError";
+	}
+};
+var SlotFillsRefusedError = class extends Error {
+	entries;
+	constructor(entries) {
+		super(slotFillsRefusedMessage(entries));
+		this.name = "SlotFillsRefusedError";
+		this.entries = entries;
+	}
+};
+function slotFillCopyId(entry, index) {
+	return entry.fill?.id ?? String(index);
+}
+function slotFillsConflict(options) {
+	return options?.fills && (options.fill || options.source) ? new SlotFillsConflictError() : void 0;
+}
+function assertSlotPrintOptions(options) {
+	const conflict = slotFillsConflict(options);
+	if (conflict) throw conflict;
+}
+/** Single-copy fill paths refuse `fills`; print and PDF jobs loop it themselves. */
+function assertSingleSlotCopy(options) {
+	const print = options;
+	assertSlotPrintOptions(print);
+	if (print?.fills) throw new RangeError("slots.fills prints one copy per entry in a PDF or print document. Pass fill or source for a single copy, to clear this refusal.");
+}
+function isSlotCopyRefusal(error) {
+	return error instanceof RequiredSlotsRefusedError || error instanceof UnmeasuredSlotsRefusedError || error instanceof SlotFillRefusedError;
+}
+function copySlots(options, entry, capture) {
+	return {
+		declarations: options.declarations,
+		resolveAsset: options.resolveAsset,
+		fill: entry.fill,
+		source: entry.source,
+		report: capture
+	};
+}
+function emptyReport(entry) {
+	return {
+		fill: entry.fill?.id ?? entry.source?.id ?? null,
+		slots: {},
+		origins: {}
+	};
+}
+function refusalFrom(error, entry, index) {
+	const id = slotFillCopyId(entry, index);
+	if (error instanceof RequiredSlotsRefusedError) return {
+		index,
+		id,
+		slots: error.slots,
+		error
+	};
+	if (error instanceof UnmeasuredSlotsRefusedError) return {
+		index,
+		id,
+		slots: error.keys.map((key) => ({
+			key,
+			state: "unmeasured"
+		})),
+		error
+	};
+	return {
+		index,
+		id,
+		slots: [],
+		error
+	};
+}
+function entryLabel(entry) {
+	return entry.id === String(entry.index) ? entry.id : `"${entry.id}"`;
+}
+function describeRefusal(entry) {
+	if (entry.error instanceof SlotFillRefusedError) return `${entryLabel(entry)} (scripts: '${entry.error.scripts}')`;
+	if (entry.slots.length === 0) return entryLabel(entry);
+	return `${entryLabel(entry)} ${entry.slots.map(({ key, state }) => `"${key}" (${state})`).join(", ")}`;
+}
+function clearsFor(entries) {
+	let required = false;
+	let unmeasured = false;
+	let scripts = false;
+	for (const entry of entries) if (entry.error instanceof RequiredSlotsRefusedError) required = true;
+	else if (entry.error instanceof UnmeasuredSlotsRefusedError) unmeasured = true;
+	else if (entry.error instanceof SlotFillRefusedError) scripts = true;
+	return [
+		required ? "Fill required slots; for an overflowed refuse slot, shorten its value or change the slot's overflow." : "",
+		unmeasured ? "Ensure each filled slot frame becomes ready before the output deadline, or change the slot's overflow from 'refuse'." : "",
+		scripts ? "Set the item's scripts to 'refuse', or show it without a fill." : ""
+	].filter(Boolean).join(" ");
+}
+function slotFillsRefusedMessage(entries) {
+	if (entries.length === 0) return "Output was refused because slots.fills has no entries. Pass at least one fill, or omit fills, to clear this refusal.";
+	return `Output was refused because fills prevent printing: ${entries.map(describeRefusal).join("; ")}. ${clearsFor(entries)}`;
+}
+async function renderOneCopy(options, entry, index, renderCopy) {
+	let lastReport;
+	const capture = options.report ? (report) => {
+		lastReport = report;
+	} : void 0;
+	try {
+		const value = await renderCopy(copySlots(options, entry, capture));
+		options.report?.(lastReport ?? emptyReport(entry));
+		return {
+			ok: true,
+			value
+		};
+	} catch (error) {
+		if (!isSlotCopyRefusal(error)) throw error;
+		options.report?.(lastReport ?? emptyReport(entry));
+		return {
+			ok: false,
+			refusal: refusalFrom(error, entry, index)
+		};
+	}
+}
+/**
+* Runs one print/PDF copy per `fills` entry, in order. Without `fills`, runs once with the given options.
+* Host `report` is called once per entry, in entry order, including refused copies.
+*/
+async function collectSlotPrintCopies(options, renderCopy) {
+	assertSlotPrintOptions(options);
+	if (!options?.fills) return [await renderCopy(options ?? {})];
+	if (options.fills.length === 0) throw new SlotFillsRefusedError([]);
+	const kept = [];
+	const refused = [];
+	for (const [index, entry] of options.fills.entries()) {
+		const outcome = await renderOneCopy(options, entry, index, renderCopy);
+		if (outcome.ok) kept.push(outcome.value);
+		else refused.push(outcome.refusal);
+	}
+	if (refused.length > 0 && (!options.skipRefused || kept.length === 0)) throw new SlotFillsRefusedError(refused);
+	return kept;
+}
+//#endregion
+export { SlotFillsConflictError, SlotFillsRefusedError, assertSingleSlotCopy, assertSlotPrintOptions, collectSlotPrintCopies, isSlotCopyRefusal, slotFillCopyId, slotFillsConflict };

package/dist/slots.d.ts

@@ -0,0 +1,26 @@
+import { RequiredSlotsRefusedError, UnmeasuredSlotsRefusedError, mergeSlotFitResults, requiredSlotRefusal, unmeasuredSlotRefusal } from "./slot-policy.js";
+import { Scripts, SlotDeclaration, SlotReport, SlotsOptions } from "@segnavia/format";
+//#region src/slots.d.ts
+export declare const MAX_SLOT_DECLARATIONS = 200;
+export interface PreparedSlots {
+  declarations: SlotDeclaration[];
+  report: SlotReport;
+  /** For each slot key, how many applications (one per rendered frame) marked it for measurement. */
+  marked: ReadonlyMap<string, number>;
+  apply(html: string): string;
+  mergeFit(slots: Record<string, 'fit' | 'shrunk' | 'overflowed'>): SlotReport;
+}
+export declare class SlotFillRefusedError extends Error {
+  readonly scripts: Exclude<Scripts, 'refuse'>;
+  constructor(scripts: Exclude<Scripts, 'refuse'>);
+}
+/** Whether an item needs slot preparation for declarations, filling, asset resolution or reporting. */
+export declare function hasSlotWork(declarations: readonly SlotDeclaration[] | undefined, options: SlotsOptions | undefined): boolean;
+/** Refuses exposing filled values to an item's own scripts. */
+export declare function slotFillRefusal(scripts: Scripts, declarations: readonly SlotDeclaration[] | undefined, options: SlotsOptions | undefined): SlotFillRefusedError | undefined;
+/** Prepares and applies the slots declared by one item. */
+export declare function prepareSlots(declarations: readonly SlotDeclaration[] | undefined, options?: SlotsOptions, signal?: AbortSignal): Promise<PreparedSlots>;
+/** Prepares one shared fill for a collection, merging each item's declarations exactly once. */
+export declare function prepareSlotCollection(groups: ReadonlyArray<readonly SlotDeclaration[] | undefined>, options?: SlotsOptions, signal?: AbortSignal): Promise<PreparedSlots>;
+//#endregion
+export { RequiredSlotsRefusedError, UnmeasuredSlotsRefusedError, mergeSlotFitResults, requiredSlotRefusal, unmeasuredSlotRefusal };

package/dist/slots.js

@@ -0,0 +1,329 @@
+import { elements, parse, serialize } from "./sanitize.js";
+import { bindingNames, hasBindings } from "./bindings.js";
+import { RequiredSlotsRefusedError, UnmeasuredSlotsRefusedError, mergeSlotFitResults, requiredSlotRefusal, unmeasuredSlotRefusal } from "./slot-policy.js";
+import { qrPayload, qrSvg } from "./qr.js";
+import { Text, isTag } from "domhandler";
+import { SlotsInput, mergeSlotDeclarations } from "@segnavia/format";
+//#region src/slots.ts
+const MAX_SLOT_DECLARATIONS = 200;
+const ASSET_RESOLUTION_CONCURRENCY = 4;
+var SlotFillRefusedError = class extends Error {
+	scripts;
+	constructor(scripts) {
+		super(`A fill was not applied because this item runs its own scripts (scripts: '${scripts}'), which could read the filled values. Set the item's scripts to 'refuse', or show it without a fill.`);
+		this.name = "SlotFillRefusedError";
+		this.scripts = scripts;
+	}
+};
+/** Whether an item needs slot preparation for declarations, filling, asset resolution or reporting. */
+function hasSlotWork(declarations, options) {
+	return Boolean(declarations?.length || options?.declarations?.length || options?.fill || options?.source || options?.resolveAsset || options?.report);
+}
+/** Refuses exposing filled values to an item's own scripts. */
+function slotFillRefusal(scripts, declarations, options) {
+	const fillsValues = (options?.fill || options?.source) && (declarations?.length || options.declarations?.length);
+	return scripts !== "refuse" && fillsValues ? new SlotFillRefusedError(scripts) : void 0;
+}
+const UNENCODED_TEXT_ELEMENTS = /* @__PURE__ */ new Set([
+	"style",
+	"script",
+	"xmp",
+	"iframe",
+	"noembed",
+	"noframes",
+	"plaintext",
+	"noscript",
+	"textarea",
+	"title"
+]);
+const VOID_ELEMENTS = /* @__PURE__ */ new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"link",
+	"meta",
+	"source",
+	"track",
+	"wbr"
+]);
+function refusesValueBinding(tag) {
+	return UNENCODED_TEXT_ELEMENTS.has(tag) || VOID_ELEMENTS.has(tag);
+}
+function assertDeclarationLimit(declarations, subject) {
+	if (declarations.length > 200) throw new RangeError(`${subject} declares ${declarations.length} slots; the limit is 200.`);
+}
+function parsedHostDeclarations(options) {
+	const declarations = options.declarations === void 0 ? [] : SlotsInput.parse(options.declarations);
+	assertDeclarationLimit(declarations, "The host");
+	return declarations;
+}
+function mergedDeclarations(groups, options) {
+	groups.forEach((group, index) => {
+		assertDeclarationLimit(group, groups.length === 1 ? "The item" : `Item ${index + 1}`);
+	});
+	return mergeSlotDeclarations(parsedHostDeclarations(options), ...groups);
+}
+function applyValue(element, name, resolved) {
+	const path = element.attribs[name];
+	if (path === void 0) return;
+	delete element.attribs[name];
+	const value = resolved.data[path];
+	if (value === void 0) return;
+	if (resolved.types[path] === "qr") {
+		const svg = qrSvg(value);
+		svg.parent = element;
+		element.children = [svg];
+		return;
+	}
+	const text = new Text(value);
+	text.parent = element;
+	element.children = [text];
+	if (element.attribs.dir === void 0) element.attribs.dir = "auto";
+}
+function invalidBinding(element, names, report) {
+	const tag = element.name.toLowerCase();
+	const value = element.attribs[names.value];
+	if (value !== void 0 && report.slots[value] !== void 0 && refusesValueBinding(tag)) {
+		report.slots[value] = "invalid";
+		return `Slot "${value}" uses a value binding on <${tag}>, whose content cannot be filled safely.`;
+	}
+	const src = element.attribs[names.src];
+	if (src !== void 0 && report.slots[src] !== void 0 && tag !== "img") {
+		report.slots[src] = "invalid";
+		return `Slot "${src}" uses a src binding on <${tag}>; src bindings are allowed only on <img>.`;
+	}
+	const href = element.attribs[names.href];
+	if (href !== void 0 && report.slots[href] !== void 0 && tag !== "a" && tag !== "area") {
+		report.slots[href] = "invalid";
+		return `Slot "${href}" uses an href binding on <${tag}>; href bindings are allowed only on <a> and <area>.`;
+	}
+}
+function applyUrl(element, attribute, name, resolved) {
+	const path = element.attribs[name];
+	if (path === void 0) return;
+	delete element.attribs[name];
+	const value = resolved.data[path];
+	if (typeof value !== "string") return;
+	if (attribute === "src") {
+		if (/^data:image\//i.test(value)) element.attribs.src = value;
+		return;
+	}
+	try {
+		if (resolved.linkOrigins.has(new URL(value).origin)) element.attribs.href = value;
+	} catch {}
+}
+function applyPresent(element, name, report) {
+	const path = element.attribs[name];
+	if (path === void 0) return true;
+	delete element.attribs[name];
+	return report.fill === null || report.slots[path] === "filled";
+}
+function markOverflow(element, names, resolved) {
+	if (resolved.report.fill === null) return;
+	for (const binding of Object.values(names)) {
+		const key = element.attribs[binding];
+		if (key === void 0) continue;
+		const declaration = resolved.declarations.get(key);
+		const overflow = declaration?.overflow ?? "wrap";
+		if (!declaration || overflow === "wrap" || resolved.report.slots[key] !== "filled") continue;
+		element.attribs["data-slot-overflow"] = `${encodeURIComponent(key)}:${overflow}${overflow === "shrink" ? `:${declaration.minSize ?? 6}` : ""}`;
+		resolved.markedHere.add(key);
+		return;
+	}
+}
+function applyElements(elements, names, resolved) {
+	return elements.flatMap((element) => {
+		if (!applyPresent(element, names.present, resolved.report)) return [];
+		delete element.attribs["data-slot-overflow"];
+		markOverflow(element, names, resolved);
+		applyValue(element, names.value, resolved);
+		applyUrl(element, "href", names.href, resolved);
+		applyUrl(element, "src", names.src, resolved);
+		element.children = element.children.flatMap((child) => {
+			if (!isTag(child)) return [child];
+			return applyElements([child], names, resolved).map((kept) => {
+				kept.parent = element;
+				return kept;
+			});
+		});
+		return [element];
+	});
+}
+function bindingRefusal(roots, names, resolved) {
+	const reasons = [];
+	const visit = (element) => {
+		const reason = invalidBinding(element, names, resolved.report);
+		if (reason) reasons.push(reason);
+		for (const child of element.children) if (isTag(child)) visit(child);
+	};
+	for (const root of roots) visit(root);
+	if (reasons.length === 0) return void 0;
+	resolved.reportState?.(resolved.report);
+	return new RangeError(reasons.join(" "));
+}
+function validString(type, value) {
+	if (type === "email") return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+	if (type === "qr") return qrPayload(value) !== void 0;
+	if (type === "link") try {
+		return new URL(value).protocol === "https:";
+	} catch {
+		return false;
+	}
+	if (type === "image") return /^data:image\//i.test(value);
+	return true;
+}
+function assetResolver(options, signal) {
+	const cached = /* @__PURE__ */ new Map();
+	const waiting = [];
+	let running = 0;
+	const acquire = () => {
+		if (running < ASSET_RESOLUTION_CONCURRENCY) {
+			running++;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => waiting.push(resolve));
+	};
+	const release = () => {
+		const next = waiting.shift();
+		if (next) next();
+		else running--;
+	};
+	return (ref) => {
+		const held = cached.get(ref);
+		if (held) return held;
+		const resolution = (async () => {
+			if (!options.resolveAsset) return void 0;
+			await acquire();
+			try {
+				return await options.resolveAsset(ref, { signal });
+			} catch {
+				return;
+			} finally {
+				release();
+			}
+		})();
+		cached.set(ref, resolution);
+		return resolution;
+	};
+}
+async function valueFor(slot, value, resolveAsset) {
+	if (value === void 0) {
+		if (slot.placeholder === void 0) return { state: "unavailable" };
+		return validString(slot.type, slot.placeholder) ? {
+			value: slot.placeholder,
+			state: "placeholder"
+		} : { state: "invalid" };
+	}
+	if (typeof value === "string") return validString(slot.type, value) ? {
+		value,
+		state: "filled"
+	} : { state: "invalid" };
+	if (slot.type !== "image" || !value || typeof value.asset !== "string") return { state: "invalid" };
+	const resolved = await resolveAsset(value.asset);
+	if (resolved === void 0) return { state: "unavailable" };
+	return /^data:image\//i.test(resolved) ? {
+		value: resolved,
+		state: "filled"
+	} : { state: "invalid" };
+}
+function layeredValue(key, options) {
+	const hand = options.fill?.values[key];
+	if (hand !== void 0 && hand !== "") return {
+		value: hand,
+		origin: "hand"
+	};
+	const source = options.source?.values[key];
+	if (source !== void 0 && source !== "") return {
+		value: source,
+		origin: "source"
+	};
+	return {};
+}
+async function resolveSlots(declarations, options, signal) {
+	const data = {};
+	const types = {};
+	const states = {};
+	const origins = {};
+	const linkOrigins = /* @__PURE__ */ new Set();
+	const resolveAsset = assetResolver(options, signal);
+	await Promise.all(declarations.map(async (slot) => {
+		types[slot.key] = slot.type;
+		const selected = layeredValue(slot.key, options);
+		const resolved = await valueFor(slot, selected.value, resolveAsset);
+		states[slot.key] = resolved.state;
+		if (selected.origin) origins[slot.key] = selected.origin;
+		if (resolved.value !== void 0) {
+			data[slot.key] = resolved.value;
+			if (slot.type === "link" && resolved.state === "filled") linkOrigins.add(new URL(resolved.value).origin);
+		}
+	}));
+	signal.throwIfAborted();
+	const report = {
+		fill: options.fill?.id ?? options.source?.id ?? null,
+		slots: states,
+		origins
+	};
+	options.report?.(report);
+	return {
+		data,
+		types,
+		report,
+		linkOrigins,
+		reportState: options.report,
+		declarations: new Map(declarations.map((slot) => [slot.key, slot])),
+		marked: /* @__PURE__ */ new Map(),
+		markedHere: /* @__PURE__ */ new Set()
+	};
+}
+function applySlots(html, resolved) {
+	if (!hasBindings(html, "slot") && !html.includes("data-slot-overflow")) return html;
+	const names = bindingNames("slot");
+	const document = parse(html);
+	const bound = elements(document.children).filter((element) => element.attribs["data-slot-overflow"] !== void 0 || Object.values(names).some((name) => element.attribs[name] !== void 0));
+	const roots = bound.filter((element) => {
+		for (let parent = element.parent; parent; parent = parent.parent) if (isTag(parent) && bound.includes(parent)) return false;
+		return true;
+	});
+	const refusal = bindingRefusal(roots, names, resolved);
+	if (refusal) throw refusal;
+	resolved.markedHere.clear();
+	const kept = applyElements(roots, names, resolved);
+	for (const key of resolved.markedHere) resolved.marked.set(key, (resolved.marked.get(key) ?? 0) + 1);
+	return roots.map((root) => ({
+		start: root.startIndex,
+		end: root.endIndex,
+		html: kept.includes(root) ? serialize(root) : ""
+	})).filter((part) => part.start !== null && part.end !== null).sort((a, b) => b.start - a.start).reduce((output, part) => `${output.slice(0, part.start)}${part.html}${output.slice(part.end + 1)}`, html);
+}
+async function prepared(declarations, options, signal) {
+	const resolved = await resolveSlots(declarations, options, signal);
+	const result = {
+		declarations,
+		report: resolved.report,
+		marked: resolved.marked,
+		apply: (html) => applySlots(html, resolved),
+		mergeFit: (slots) => {
+			const report = mergeSlotFitResults(declarations, result.report, slots);
+			result.report = report;
+			resolved.report = report;
+			options.report?.(report);
+			return report;
+		}
+	};
+	return result;
+}
+/** Prepares and applies the slots declared by one item. */
+async function prepareSlots(declarations, options = {}, signal = new AbortController().signal) {
+	return prepared(mergedDeclarations([declarations ?? []], options), options, signal);
+}
+/** Prepares one shared fill for a collection, merging each item's declarations exactly once. */
+async function prepareSlotCollection(groups, options = {}, signal = new AbortController().signal) {
+	return prepared(mergedDeclarations(groups.map((group) => group ?? []), options), options, signal);
+}
+//#endregion
+export { MAX_SLOT_DECLARATIONS, RequiredSlotsRefusedError, SlotFillRefusedError, UnmeasuredSlotsRefusedError, hasSlotWork, mergeSlotFitResults, prepareSlotCollection, prepareSlots, requiredSlotRefusal, slotFillRefusal, unmeasuredSlotRefusal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segnavia/html",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -26,9 +26,10 @@
     }
   },
   "dependencies": {
-    "@segnavia/format": "0.21.0",
-    "htmlparser2": "^10.0.0",
+    "@segnavia/format": "0.23.0",
+    "dom-serializer": "^2.0.0",
     "domhandler": "^5.0.3",
-    "dom-serializer": "^2.0.0"
+    "htmlparser2": "^10.0.0",
+    "qrcode-generator": "2.0.4"
   }
 }