@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/author-html.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Elements that survive: HTML flow and phrasing content, a strict subset of
+ * DOMPurify's `USE_PROFILES: { html: true }` set minus the tags both callers
+ * already forbade (`script`, `iframe`, `object`, `embed`, `form`, `base`)
+ * and minus every interactive form control, which no author markup on a
+ * rendered page has a use for and which carries `formaction` shapes.
+ */
+export declare const ALLOWED_AUTHOR_HTML_ELEMENTS: ReadonlySet<string>;
+/**
+ * The subset of {@link ALLOWED_AUTHOR_HTML_ELEMENTS} that may appear inside a
+ * control — a `<button>` or an `<a>` (AGL-2557).
+ *
+ * Both have a content model of phrasing content with NO interactive
+ * descendant. Serving a `<ul>`, a `<div>` or a nested `<a>` inside one is not
+ * a styling problem: the parser closes the control early and promotes the
+ * rest to a sibling, so React hydrates against a tree it did not describe and
+ * reports the mismatch — the same shape `authorHtmlBreaksContainer` exists to
+ * head off for a `<p>`. A nested control is also unreachable by keyboard and
+ * announces as neither of the two things it is.
+ *
+ * Narrowing keeps LESS than the full allowlist, so the subset argument in
+ * this module's header still holds: everything emitted under it is something
+ * the full policy would also have kept. `img` is out with the rest of the
+ * embedded content — an author who wants an icon on a button has the icon
+ * fields for it, and nothing in the inline editor can produce one.
+ */
+export declare const INLINE_AUTHOR_HTML_ELEMENTS: ReadonlySet<string>;
+/** Attributes any allowed element may carry. */
+export declare const GLOBAL_AUTHOR_HTML_ATTRIBUTES: ReadonlySet<string>;
+/** Attributes allowed only on the elements that define them. */
+export declare const AUTHOR_HTML_ELEMENT_ATTRIBUTES: Readonly<Record<string, ReadonlySet<string>>>;
+/**
+ * Decodes character references in an attribute value the way a browser will,
+ * so the value can be JUDGED as the browser will see it.
+ *
+ * Numeric references are decoded generically — that is the form that can
+ * produce any character at all, and the only form that can spell a scheme.
+ * Named references are decoded from {@link NAMED_REFERENCES}; anything else
+ * is left verbatim, which is safe precisely because it cannot become a
+ * letter or a colon. Everything decoded here is re-escaped on output, so the
+ * emitted attribute value and the validated value are the same string.
+ */
+export declare function decodeCharacterReferences(value: string): string;
+/**
+ * Whether a decoded URL clears the scheme rule for this tag/attribute.
+ *
+ * The comparison is made on a copy with every C0 control and space removed
+ * and folded to lower case, because browsers strip exactly those while
+ * resolving a scheme — `"java\tscript:alert(1)"` navigates.
+ *
+ * Exported because the sanitizer is not the only reader of author markup
+ * (AGL-2740). The Markdown representation of a page converts the same stored
+ * fragment without sanitizing it, and a scheme rule it re-spelled for itself
+ * is a scheme rule that can disagree — which is how `screen:` survived into a
+ * link target the page itself refuses to render.
+ */
+export declare function isAllowedAuthorHtmlUrl(tag: string, attribute: string, decoded: string): boolean;
+/**
+ * Whether `container` would be TORN OPEN by the sanitized body put inside it.
+ *
+ * The caller renders the body with `dangerouslySetInnerHTML` inside an
+ * element of its own choosing, and that element is part of the served
+ * document — so the parser's implied end tags apply to it exactly as they do
+ * inside the body. A `<p>` holding an `<h2>`, or an `<h2>` holding an
+ * `<h2>`, is closed early by the parser, the rest of the body becomes a
+ * SIBLING, and React hydrates against a tree it did not describe.
+ *
+ * Lives here rather than in the caller so the rule and the
+ * {@link CLOSES_OPEN_P} table cannot drift apart; `typography.tsx` uses it to
+ * fall back to a `<div>`, which no start tag implies an end tag for.
+ *
+ * Pure, so the server and the client reach the same answer.
+ */
+export declare function authorHtmlBreaksContainer(sanitized: string, container: string): boolean;
+/**
+ * Something this sanitizer took OUT, phrased for the author who typed it
+ * (AGL-2486).
+ *
+ * Collected BY the sanitizer, at the point each decision is made, rather
+ * than re-derived by a second scan of the input. That is the whole design
+ * constraint: this module's header refuses to let the policy exist in two
+ * engines, and a warning that re-implements the rules is a second engine —
+ * one that goes quietly wrong the moment the real rules move, and tells the
+ * author their markup is fine while the page drops it.
+ *
+ * The render path never asks for these. They exist for the AUTHORING side,
+ * which is the only place a person who can fix the markup is standing; the
+ * runtime is executing for a VISITOR and can do nothing but drop the value
+ * silently. Same reasoning as the reserved-name refusal in `actions.ts`.
+ */
+export interface AuthorHtmlRemoval {
+    kind: 'element' | 'attribute' | 'style' | 'url';
+    /** One sentence, addressed to the author, naming what is gone and why. */
+    message: string;
+}
+/**
+ * Sanitizes author-written HTML to a string safe to hand
+ * `dangerouslySetInnerHTML`, on the server and in the browser alike.
+ *
+ * Pure and deterministic: the same input yields the same bytes in Node and
+ * in a browser, which is what lets the server render and the first client
+ * render agree without an effect (AGL-1901).
+ *
+ * `removals`, when passed, is APPENDED to with an {@link AuthorHtmlRemoval}
+ * for each thing dropped (AGL-2486). It changes nothing about the output —
+ * every existing caller is byte-identical whether it passes one or not — so
+ * the render path stays exactly as pure as it was and only the editor pays
+ * for the bookkeeping.
+ *
+ * `options.allowedElements` narrows the element allowlist for one call
+ * (AGL-2557). The only value it is given in this repo is
+ * {@link INLINE_AUTHOR_HTML_ELEMENTS}, by the components that render their
+ * label inside a control. A caller may narrow but never widen: a set with a
+ * tag the module's own allowlist refuses would reopen the policy, so the two
+ * are intersected rather than substituted.
+ */
+export declare function sanitizeAuthorHtml(html: string, removals?: AuthorHtmlRemoval[], options?: {
+    allowedElements?: ReadonlySet<string>;
+}): string;