@pygmalionjs/pygmalion 0.8.1 → 0.10.0

package/dist-lib/types/document/prototype.d.ts

@@ -0,0 +1,424 @@
+/**
+ * Prototype model and interpreter.
+ *
+ * Interactions live on layers (`node.properties.interactions`); flows, variables and presentation
+ * settings live in `document.metadata.prototype`. Both are plain DocumentValue shapes, so the
+ * document engine persists, validates and undoes them like any other design property. The
+ * interpreter is pure: `stepPrototype(document, state, event, now)` returns the next state and the
+ * side effects a player must perform; time enters only through `now`.
+ */
+import type { DesignDocument, DocumentDiagnostic, DocumentDuplicateMetadataRemapper, DocumentNode, DocumentResolveOptions, DocumentTransaction, ResolvedDocumentNode } from './contracts.js';
+export declare const PROTOTYPE_METADATA_KEY = "prototype";
+export declare const PROTOTYPE_INTERACTIONS_PROPERTY = "interactions";
+/** Upper bound for an authored transition in this player. */
+export declare const PROTOTYPE_MAX_DURATION_MS = 10000;
+export declare const prototypeTriggerTypes: readonly ["click", "drag", "hover", "press", "key", "mouse-enter", "mouse-leave", "mouse-down", "mouse-up", "delay"];
+export type PrototypeTriggerType = typeof prototypeTriggerTypes[number];
+export declare const prototypeTriggerLabels: Record<PrototypeTriggerType, string>;
+export interface PrototypeTrigger {
+    type: PrototypeTriggerType;
+    key?: string;
+    delayMs?: number;
+}
+export declare const prototypeTransitionTypes: readonly ["instant", "dissolve", "smart-animate", "move-in", "move-out", "push", "slide-in", "slide-out"];
+export type PrototypeTransitionType = typeof prototypeTransitionTypes[number];
+export declare const prototypeTransitionLabels: Record<PrototypeTransitionType, string>;
+export declare const prototypeDirectionalTransitions: ReadonlySet<PrototypeTransitionType>;
+export declare const prototypeDirections: readonly ["left", "right", "up", "down"];
+export type PrototypeDirection = typeof prototypeDirections[number];
+export declare const prototypeEasingTypes: readonly ["linear", "ease-in", "ease-out", "ease-in-out", "ease-in-back", "ease-out-back", "ease-in-out-back", "custom-bezier", "spring"];
+export type PrototypeEasingType = typeof prototypeEasingTypes[number];
+export declare const prototypeSpringPresets: readonly ["gentle", "quick", "bouncy", "slow", "custom"];
+export type PrototypeSpringPreset = typeof prototypeSpringPresets[number];
+export type PrototypeEasing = {
+    type: Exclude<PrototypeEasingType, 'custom-bezier' | 'spring'>;
+} | {
+    type: 'custom-bezier';
+    bezier: [number, number, number, number];
+} | {
+    type: 'spring';
+    preset: PrototypeSpringPreset;
+    mass?: number;
+    stiffness?: number;
+    damping?: number;
+};
+export interface PrototypeTransition {
+    type: PrototypeTransitionType;
+    direction?: PrototypeDirection;
+    durationMs: number;
+    easing: PrototypeEasing;
+    /** Move, push and slide transitions may also animate layers that share a name. */
+    matchLayers?: boolean;
+}
+export declare const prototypeOverlayPositions: readonly ["center", "top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right", "manual"];
+export type PrototypeOverlayPosition = typeof prototypeOverlayPositions[number];
+export interface PrototypeOverlaySettings {
+    position: PrototypeOverlayPosition;
+    x?: number;
+    y?: number;
+    closeOnOutsideClick: boolean;
+    background?: {
+        color: string;
+        opacity: number;
+    } | null;
+}
+export declare const prototypeVariableTypes: readonly ["boolean", "number", "string", "color"];
+export type PrototypeVariableType = typeof prototypeVariableTypes[number];
+export type PrototypeValue = boolean | number | string;
+export interface PrototypeVariable {
+    id: string;
+    name: string;
+    type: PrototypeVariableType;
+    value: PrototypeValue;
+    description?: string;
+}
+export declare const prototypeBinaryOperators: readonly ["+", "-", "*", "/", "%", "==", "!=", "<", "<=", ">", ">=", "and", "or"];
+export type PrototypeBinaryOperator = typeof prototypeBinaryOperators[number];
+export type PrototypeExpression = {
+    kind: 'literal';
+    value: PrototypeValue;
+} | {
+    kind: 'variable';
+    variableId: string;
+} | {
+    kind: 'unary';
+    operator: 'not' | 'negate';
+    operand: PrototypeExpression;
+} | {
+    kind: 'binary';
+    operator: PrototypeBinaryOperator;
+    left: PrototypeExpression;
+    right: PrototypeExpression;
+};
+export declare const prototypeActionTypes: readonly ["navigate", "change-to", "open-overlay", "swap-overlay", "close-overlay", "back", "scroll-to", "open-url", "set-variable", "conditional"];
+export type PrototypeActionType = typeof prototypeActionTypes[number];
+export declare const prototypeActionLabels: Record<PrototypeActionType, string>;
+export type PrototypeAction = {
+    type: 'navigate';
+    destinationId: string;
+    transition: PrototypeTransition;
+    preserveScroll?: boolean;
+}
+/** Switches the enclosing instance to another component definition (a variant). */
+ | {
+    type: 'change-to';
+    destinationId: string;
+    transition: PrototypeTransition;
+} | {
+    type: 'open-overlay';
+    destinationId: string;
+    transition: PrototypeTransition;
+    overlay: PrototypeOverlaySettings;
+} | {
+    type: 'swap-overlay';
+    destinationId: string;
+    transition: PrototypeTransition;
+} | {
+    type: 'close-overlay';
+    transition: PrototypeTransition;
+} | {
+    type: 'back';
+    transition: PrototypeTransition;
+} | {
+    type: 'scroll-to';
+    targetId: string;
+    transition: PrototypeTransition;
+} | {
+    type: 'open-url';
+    url: string;
+    newTab?: boolean;
+} | {
+    type: 'set-variable';
+    variableId: string;
+    value: PrototypeExpression;
+} | {
+    type: 'conditional';
+    branches: {
+        condition: PrototypeExpression;
+        actions: PrototypeAction[];
+    }[];
+    otherwise?: PrototypeAction[];
+};
+export interface PrototypeInteraction {
+    id: string;
+    trigger: PrototypeTrigger;
+    actions: PrototypeAction[];
+}
+export interface PrototypeFlow {
+    id: string;
+    name: string;
+    startingNodeId: string;
+    description?: string;
+}
+export interface PrototypeSettings {
+    background?: string;
+}
+export interface PrototypeDocument {
+    version: 1;
+    flows: PrototypeFlow[];
+    variables: PrototypeVariable[];
+    settings?: PrototypeSettings;
+}
+export declare const PROTOTYPE_VARIABLE_NAME: RegExp;
+export declare function defaultPrototypeTransition(type?: PrototypeTransitionType, direction?: PrototypeDirection): PrototypeTransition;
+export declare function defaultPrototypeOverlaySettings(): PrototypeOverlaySettings;
+export declare function defaultPrototypeAction(type: PrototypeActionType, destinationId?: string): PrototypeAction;
+export declare function defaultPrototypeTrigger(type: PrototypeTriggerType): PrototypeTrigger;
+/** CSS timing function for an easing; springs are approximated by the closest cubic curve. */
+export declare function prototypeEasingCss(easing: PrototypeEasing): string;
+/** Where an overlay sits inside its screen; manual positions are authored in screen coordinates. */
+export declare function prototypeOverlayPlacement(settings: PrototypeOverlaySettings, screen: {
+    width: number;
+    height: number;
+}, overlay: {
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+};
+export type PrototypeExpressionResult = {
+    expression: PrototypeExpression;
+    error?: undefined;
+} | {
+    expression?: undefined;
+    error: string;
+};
+/** Parses `count + 1`, `isOpen and total >= 3`, `"Hello, " + name`; variables are referenced by name. */
+export declare function parsePrototypeExpression(source: string, variables: readonly PrototypeVariable[]): PrototypeExpressionResult;
+/** Inverse of the parser; unknown variables print as their id so nothing is silently lost. */
+export declare function formatPrototypeExpression(expression: PrototypeExpression, variables: readonly PrototypeVariable[]): string;
+export type PrototypeValueType = 'boolean' | 'number' | 'string';
+export type PrototypeTypeResult = {
+    type: PrototypeValueType;
+    error?: undefined;
+} | {
+    type?: undefined;
+    error: string;
+};
+/** Static type of an expression against the declared variables. */
+export declare function prototypeExpressionType(expression: PrototypeExpression, variables: readonly PrototypeVariable[]): PrototypeTypeResult;
+export type PrototypeEvaluation = {
+    value: PrototypeValue;
+    error?: undefined;
+} | {
+    value?: undefined;
+    error: string;
+};
+export declare function evaluatePrototypeExpression(expression: PrototypeExpression, values: Readonly<Record<string, PrototypeValue>>): PrototypeEvaluation;
+export declare function prototypeValueAssignable(variable: PrototypeVariable, value: PrototypeValue): boolean;
+export declare function isPrototypeTransition(value: unknown): value is PrototypeTransition;
+export declare function isPrototypeOverlaySettings(value: unknown): value is PrototypeOverlaySettings;
+export declare function isPrototypeExpression(value: unknown): value is PrototypeExpression;
+export declare function isPrototypeTrigger(value: unknown): value is PrototypeTrigger;
+export declare function isPrototypeAction(value: unknown, depth?: number): value is PrototypeAction;
+export declare function isPrototypeInteraction(value: unknown): value is PrototypeInteraction;
+export declare function isPrototypeVariable(value: unknown): value is PrototypeVariable;
+export declare function isPrototypeFlow(value: unknown): value is PrototypeFlow;
+export declare function isPrototypeDocument(value: unknown): value is PrototypeDocument;
+export declare function emptyPrototypeDocument(): PrototypeDocument;
+/** The document's prototype sidecar, or an empty one; malformed sidecars are reported by `validatePrototype`. */
+export declare function readPrototypeDocument(document: DesignDocument): PrototypeDocument;
+export declare function writePrototypeDocument(transaction: DocumentTransaction, value: PrototypeDocument | null): void;
+/** Well-formed interactions of a (resolved or canonical) node; malformed entries are skipped here and reported by validation. */
+export declare function nodeInteractions(node: Pick<DocumentNode, 'properties'>): PrototypeInteraction[];
+export declare function writeNodeInteractions(transaction: DocumentTransaction, node: DocumentNode, interactions: readonly PrototypeInteraction[]): void;
+export declare function hasPrototypeInteractions(node: Pick<DocumentNode, 'properties'>): boolean;
+/** Remaps only explicit node destinations; variable identities remain scoped to the same prototype. */
+export declare function remapPrototypeInteractions(interactions: readonly PrototypeInteraction[], nodeIds: Readonly<Record<string, string>>): PrototypeInteraction[];
+/** Existing flows keep their starting nodes; duplicating a layer does not create another flow. */
+export declare function prototypeDuplicateRemapper(inner?: DocumentDuplicateMetadataRemapper): DocumentDuplicateMetadataRemapper;
+/** Prototype destinations are the root's container children, the equivalent of Figma's top-level frames. */
+export declare function prototypeScreens(document: DesignDocument): DocumentNode[];
+export declare function isPrototypeScreen(document: DesignDocument, nodeId: string): boolean;
+/** The screen that contains a node (itself when it is a screen); null for the root. */
+export declare function prototypeScreenOf(document: DesignDocument, nodeId: string): string | null;
+export declare function prototypeUrlValid(url: string): boolean;
+/** Cross-references and Figma rules for every interaction, flow and variable; codes are `prototype-*`. */
+export declare function validatePrototype(document: DesignDocument): DocumentDiagnostic[];
+export interface PrototypeSceneLayer {
+    /** Source (definition-relative) node id, the id a DOM surface reports back in event paths. */
+    nodeId: string;
+    path: string[];
+    /** Names from the scene root down to this layer, the smart-animate hierarchy key. */
+    namePath: string;
+    name: string;
+    kind: DocumentNode['kind'];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    opacity: number;
+    fill: string | null;
+    node: DocumentNode;
+    depth: number;
+}
+/** Stable occurrence key. Every ID is opaque; nested instances never share canonical state. */
+export declare function prototypeVariantKey(instancePath: readonly string[]): string;
+/** Presentation-only variant resolution; neither the document nor shared definitions are changed. */
+export declare function prototypeResolveOptions(document: DesignDocument, variants: Readonly<Record<string, string>>): DocumentResolveOptions;
+/** Resolves runtime variants explicitly; invalid choices never silently render canonical state. */
+export declare function resolvePrototypeScene(document: DesignDocument, rootId: string, variants?: Readonly<Record<string, string>>): ResolvedDocumentNode;
+export declare function prototypeSceneLayers(document: DesignDocument, rootId: string, variants?: Readonly<Record<string, string>>): PrototypeSceneLayer[];
+export interface PrototypeSmartAnimatePair {
+    name: string;
+    from: PrototypeSceneLayer;
+    to: PrototypeSceneLayer;
+}
+export interface PrototypeSmartAnimatePlan {
+    pairs: PrototypeSmartAnimatePair[];
+    leaving: PrototypeSceneLayer[];
+    entering: PrototypeSceneLayer[];
+}
+/** Smart animate pairs equal names within equal hierarchy paths. Unmatched layers fade. */
+export declare function matchSmartAnimateLayers(document: DesignDocument, fromScreenId: string, toScreenId: string, variants?: Readonly<Record<string, string>>): PrototypeSmartAnimatePlan;
+export interface PrototypeTimer {
+    id: string;
+    at: number;
+    sceneId: string;
+    nodeId: string;
+    interactionId: string;
+}
+export interface PrototypeOverlayState {
+    id: string;
+    nodeId: string;
+    settings: PrototypeOverlaySettings;
+    transition: PrototypeTransition;
+    openedAt: number;
+}
+export type PrototypeRevert = {
+    type: 'variant';
+    instanceId: string;
+    definitionId: string | null;
+} | {
+    type: 'screen';
+    screenId: string;
+    transition: PrototypeTransition;
+} | {
+    type: 'overlay';
+    overlayId: string;
+};
+export interface PrototypeHold {
+    nodeId: string;
+    trigger: 'hover' | 'press';
+    /** Screen-space bounds of the hotspot when the hold began; a surface keeps it hit-testable across navigation. */
+    bounds: {
+        sceneId: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    reverts: PrototypeRevert[];
+}
+export type PrototypeTransitionKind = 'start' | 'navigate' | 'back' | 'overlay-open' | 'overlay-close' | 'overlay-swap';
+export interface PrototypeTransitionState {
+    kind: PrototypeTransitionKind;
+    fromScreenId: string | null;
+    toScreenId: string | null;
+    overlayId: string | null;
+    transition: PrototypeTransition;
+    startedAt: number;
+    endsAt: number;
+}
+export interface PrototypeState {
+    flowId: string | null;
+    screenId: string;
+    history: string[];
+    overlays: PrototypeOverlayState[];
+    variables: Record<string, PrototypeValue>;
+    /** Runtime variant choices keyed by prototypeVariantKey(outer-to-inner instance path). */
+    variants: Record<string, string>;
+    scroll: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    scrollTarget: {
+        sceneId: string;
+        targetId: string;
+        transition: PrototypeTransition;
+        at: number;
+    } | null;
+    timers: PrototypeTimer[];
+    holds: PrototypeHold[];
+    transition: PrototypeTransitionState | null;
+    sequence: number;
+    startedAt: number;
+    now: number;
+}
+export type PrototypePointerEventType = 'click' | 'drag' | 'mouse-enter' | 'mouse-leave' | 'mouse-down' | 'mouse-up' | 'hover-start' | 'hover-end' | 'press-start' | 'press-end';
+export type PrototypeEvent = 
+/** `path` lists source node ids from the hit layer up to its scene root. */
+{
+    type: PrototypePointerEventType;
+    path: readonly string[];
+} | {
+    type: 'key';
+    key: string;
+} | {
+    type: 'outside-click';
+} | {
+    type: 'tick';
+} | {
+    type: 'scroll';
+    sceneId: string;
+    x: number;
+    y: number;
+} | {
+    type: 'restart';
+    flowId?: string | null;
+};
+export type PrototypeEffect = {
+    type: 'fired';
+    nodeId: string;
+    interactionId: string;
+    trigger: PrototypeTriggerType;
+} | {
+    type: 'navigated';
+    kind: PrototypeTransitionKind;
+    fromScreenId: string | null;
+    toScreenId: string;
+    transition: PrototypeTransition;
+} | {
+    type: 'overlay';
+    kind: 'opened' | 'closed' | 'swapped';
+    overlayId: string;
+    nodeId: string;
+} | {
+    type: 'variable';
+    variableId: string;
+    value: PrototypeValue;
+} | {
+    type: 'variant';
+    instanceId: string;
+    definitionId: string | null;
+} | {
+    type: 'scroll-to';
+    sceneId: string;
+    targetId: string;
+    transition: PrototypeTransition;
+} | {
+    type: 'open-url';
+    url: string;
+    newTab: boolean;
+} | {
+    type: 'diagnostic';
+    code: string;
+    message: string;
+    nodeId?: string;
+};
+export interface PrototypeStepResult {
+    state: PrototypeState;
+    effects: PrototypeEffect[];
+}
+export interface PrototypeStartOptions {
+    flowId?: string | null;
+    startingNodeId?: string;
+    now?: number;
+}
+/** The initial state of a flow (or of an explicit starting screen); delay triggers on the screen are armed. */
+export declare function createPrototypeState(document: DesignDocument, options?: PrototypeStartOptions): PrototypeState;
+/** The earliest moment the state changes without input, or null when it is at rest. */
+export declare function prototypeNextDeadline(state: PrototypeState): number | null;
+/** One pure step: the event (or the passage of time) against a frozen document; time is `now`. */
+export declare function stepPrototype(document: DesignDocument, previous: PrototypeState, event: PrototypeEvent, now: number): PrototypeStepResult;

package/dist-lib/types/document/prototypeReferences.d.ts

@@ -0,0 +1,3 @@
+import type { DocumentValue } from './contracts.js';
+/** Known prototype destinations follow copied layers. External destinations and variable IDs stay shared. */
+export declare function remapPrototypeProperties(properties: Record<string, DocumentValue>, nodeIds: Readonly<Record<string, string>>): Record<string, DocumentValue>;

package/dist-lib/types/document/richText.d.ts

@@ -0,0 +1,185 @@
+import type { DesignDocument, DocumentNode, DocumentValue } from './contracts.js';
+/**
+ * Rich text for `kind: 'text'` nodes.
+ *
+ * The plain string `properties.text` stays the canonical content that bindings and the
+ * visual source compiler read. `properties.richText` is an optional sidecar that holds
+ * per-range character styles and per-paragraph styles; `normalizeTextProperties` is the
+ * single function that keeps the two in sync and it is the only writer either path uses.
+ *
+ * Style that applies to the whole layer is stored on node-level properties, never in runs.
+ * Normalization hoists any key shared by every run (or every paragraph) to the node level
+ * and drops the sidecar when nothing per-range remains, so a stored `richText` always
+ * means "this layer has mixed styling" — the exact condition that blocks plain source output.
+ */
+export type RichTextCase = 'none' | 'upper' | 'lower' | 'title';
+export type RichTextList = 'none' | 'bullet' | 'numbered';
+export type RichTextAlign = 'start' | 'center' | 'end' | 'justify';
+/** The component measures; the document records only the mode. */
+export type TextResizeMode = 'fixed' | 'auto-width' | 'auto-height';
+export interface RichTextCharacterStyle {
+    fontFamily?: string;
+    /** CSS numeric weight, 1–1000. */
+    fontWeight?: number;
+    /** Pixels. Node-level `fontSize` may also be a permitted CSS token string. */
+    fontSize?: number;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    textCase?: RichTextCase;
+    color?: string;
+    /** A link target; only http(s), mailto, tel, and relative targets validate. */
+    link?: string;
+}
+export interface RichTextParagraphStyle {
+    align?: RichTextAlign;
+    /** Unitless multiplier. */
+    lineHeight?: number;
+    /** Pixels; negative values tighten. */
+    letterSpacing?: number;
+    list?: RichTextList;
+    /** Indent level, 0–10. */
+    indent?: number;
+}
+export interface RichTextRun {
+    text: string;
+    style: RichTextCharacterStyle;
+}
+export interface RichTextParagraph {
+    runs: RichTextRun[];
+    style: RichTextParagraphStyle;
+}
+export interface RichText {
+    version: 1;
+    paragraphs: RichTextParagraph[];
+}
+/** Offsets into the plain projection, where paragraphs are joined by one `\n`. */
+export interface RichTextRange {
+    start: number;
+    end: number;
+}
+/** Node-level defaults; `fontSize` may be a CSS token the visual compiler already accepts. */
+export interface TextNodeCharacterStyle extends Omit<RichTextCharacterStyle, 'fontSize'> {
+    fontSize?: number | string;
+}
+export interface TextNodeStyle {
+    character: TextNodeCharacterStyle;
+    paragraph: RichTextParagraphStyle;
+}
+export declare const TEXT_CHARACTER_KEYS: readonly ["fontFamily", "fontWeight", "fontSize", "italic", "underline", "strikethrough", "textCase", "color", "link"];
+export declare const TEXT_PARAGRAPH_KEYS: readonly ["align", "lineHeight", "letterSpacing", "list", "indent"];
+export type RichTextCharacterKey = typeof TEXT_CHARACTER_KEYS[number];
+export type RichTextParagraphKey = typeof TEXT_PARAGRAPH_KEYS[number];
+export declare const TEXT_RESIZE_MODES: readonly TextResizeMode[];
+export declare const RICH_TEXT_CASES: readonly RichTextCase[];
+export declare const RICH_TEXT_LISTS: readonly RichTextList[];
+export declare const RICH_TEXT_ALIGNMENTS: readonly RichTextAlign[];
+/** Node property names for paragraph keys; alignment is `textAlign` so it never reads as layout alignment. */
+export declare const TEXT_PARAGRAPH_PROPERTY: Readonly<Record<RichTextParagraphKey, string>>;
+/** Every node-level typography property, including the resize mode. */
+export declare const TEXT_NODE_PROPERTY_KEYS: readonly string[];
+export declare const isTextLink: (value: unknown) => value is string;
+export declare const isTextResizeMode: (value: unknown) => value is TextResizeMode;
+export declare const isRichTextCharacterValue: (key: RichTextCharacterKey, value: unknown) => boolean;
+export declare const isRichTextParagraphValue: (key: RichTextParagraphKey, value: unknown) => boolean;
+export declare function isRichTextCharacterStyle(value: unknown): value is RichTextCharacterStyle;
+export declare function isRichTextParagraphStyle(value: unknown): value is RichTextParagraphStyle;
+export declare function isRichTextRun(value: unknown): value is RichTextRun;
+export declare function isRichTextParagraph(value: unknown): value is RichTextParagraph;
+export declare function isRichText(value: unknown): value is RichText;
+export declare function richTextPlain(model: RichText): string;
+export declare function richTextLength(model: RichText): number;
+export declare function richTextFromPlain(text: string, style?: RichTextCharacterStyle, paragraphStyle?: RichTextParagraphStyle): RichText;
+/** Merges adjacent runs with equal styles and drops empty runs; an empty paragraph keeps one empty run for its pending style. */
+export declare function normalizeRichText(model: RichText): RichText;
+/** Sets the defined keys of `style` on every character in the range; a collapsed range changes nothing. */
+export declare function applyRichTextCharacterStyle(model: RichText, range: RichTextRange, style: RichTextCharacterStyle): RichText;
+export declare function clearRichTextCharacterStyle(model: RichText, range: RichTextRange, keys?: readonly RichTextCharacterKey[]): RichText;
+/** Sets the defined keys on every paragraph the range touches; a collapsed range targets its own paragraph. */
+export declare function setRichTextParagraphStyle(model: RichText, range: RichTextRange, style: RichTextParagraphStyle): RichText;
+export declare function clearRichTextParagraphStyle(model: RichText, range: RichTextRange, keys?: readonly RichTextParagraphKey[]): RichText;
+/** The style typed text inherits at `offset`: the run before the caret, or the run after it at a paragraph start. */
+export declare function richTextInheritedStyle(model: RichText, offset: number): RichTextCharacterStyle;
+/** Inserts plain text; each `\n` starts a new paragraph that copies the split paragraph's style. */
+export declare function insertRichText(model: RichText, offset: number, text: string, style?: RichTextCharacterStyle): RichText;
+/** Deletes a range; a boundary inside the range merges its paragraphs under the first paragraph's style. */
+export declare function deleteRichText(model: RichText, range: RichTextRange): RichText;
+/** Replaces a range with plain text that inherits the replaced text's style. */
+export declare function replaceRichText(model: RichText, range: RichTextRange, text: string, style?: RichTextCharacterStyle): RichText;
+export declare function splitRichTextParagraph(model: RichText, offset: number): RichText;
+/** Merges paragraph `index` with the one after it. */
+export declare function mergeRichTextParagraphs(model: RichText, index: number): RichText;
+/**
+ * Applies a plain-text edit (the textarea result) while runs elsewhere keep their styles. When the paragraph
+ * count is unchanged, every changed paragraph is one span replacement, so edits on different lines committed
+ * together each inherit their own neighbour; otherwise the whole differing span is replaced once.
+ */
+export declare function applyPlainTextEdit(model: RichText, nextText: string): RichText;
+export interface RichTextStyleSummary<T> {
+    style: T;
+    mixed: readonly (keyof T)[];
+}
+/** Explicit run styles inside the range (the inherited style at a collapsed range); keys that differ are reported as mixed. */
+export declare function richTextCharacterStyleAt(model: RichText, range: RichTextRange): RichTextStyleSummary<RichTextCharacterStyle>;
+export declare function richTextParagraphStyleAt(model: RichText, range: RichTextRange): RichTextStyleSummary<RichTextParagraphStyle>;
+/** Keys that vary across the whole model — the exact reason plain source output is blocked. */
+export declare function richTextVaryingKeys(model: RichText): {
+    character: readonly RichTextCharacterKey[];
+    paragraph: readonly RichTextParagraphKey[];
+};
+/** Reads the validated node-level typography; invalid values are ignored rather than rendered. */
+export declare function textNodeStyle(properties: Readonly<Record<string, DocumentValue>>): TextNodeStyle;
+export declare function textResizeMode(properties: Readonly<Record<string, DocumentValue>>): TextResizeMode;
+/** The written string; bound content is projected by the canvas and never stored here. */
+export declare function textNodePlain(properties: Readonly<Record<string, DocumentValue>>): string;
+/** The editable model. A sidecar that disagrees with the written text is dropped, because the written text is what bindings and source read. */
+export declare function textNodeModel(properties: Readonly<Record<string, DocumentValue>>): RichText;
+export declare const isRichTextTrivial: (model: RichText) => boolean;
+/** Moves styles shared by the whole text to the node level and drops run keys that repeat the node default. */
+export declare function hoistRichTextStyle(model: RichText, base: TextNodeStyle): {
+    model: RichText;
+    character: TextNodeCharacterStyle;
+    paragraph: RichTextParagraphStyle;
+};
+/** A JSON round trip drops `undefined` and prototypes so the engine accepts the value. */
+export declare const richTextValue: (model: RichText) => DocumentValue;
+/**
+ * The single writer for text properties. Given a model (or the stored sidecar), it hoists
+ * whole-text styles to node properties, writes the plain projection to `text`, and keeps
+ * `richText` only while per-range styling remains. Node-level defaults are removed rather
+ * than written, so a layer without styling has no typography keys at all.
+ */
+export declare function normalizeTextProperties(properties: Readonly<Record<string, DocumentValue>>, model?: RichText): Record<string, DocumentValue>;
+/** Bound text never carries runs: the projected value replaces the written text at render time. */
+export declare function plainTextProperties(properties: Readonly<Record<string, DocumentValue>>, text: string): Record<string, DocumentValue>;
+export interface TextFontRequirement {
+    family: string;
+    weights: readonly number[];
+}
+export interface TextFontRequest {
+    family: string;
+    weight: number;
+}
+export interface TextFontLoader {
+    load(request: TextFontRequest): Promise<boolean>;
+}
+export interface TextFontLoadReport {
+    loaded: readonly TextFontRequest[];
+    unavailable: readonly TextFontRequest[];
+    failed: readonly (TextFontRequest & {
+        message: string;
+    })[];
+}
+/** Families and weights the text needs; runs without a family use the node's, and a missing family means the platform default. */
+export declare function textFontRequirements(model: RichText, base?: TextNodeCharacterStyle): TextFontRequirement[];
+export declare function documentFontRequirements(document: DesignDocument): TextFontRequirement[];
+/** Resolves every required face through the injected loader; nothing here touches the network on its own. */
+export declare function loadTextFonts(requirements: readonly TextFontRequirement[], loader: TextFontLoader): Promise<TextFontLoadReport>;
+export declare function loadDocumentFonts(document: DesignDocument, loader: TextFontLoader): Promise<TextFontLoadReport>;
+/** Adapts the browser `document.fonts` set when the host runs in a browser; returns null elsewhere. */
+export declare function fontFaceSetLoader(fonts: {
+    load(font: string): Promise<unknown[]>;
+    check(font: string): boolean;
+} | undefined | null): TextFontLoader | null;
+/** A convenience for text nodes: the node's own font needs. */
+export declare function textNodeFontRequirements(node: DocumentNode): TextFontRequirement[];