@pygmalionjs/pygmalion 0.5.13 → 0.5.15

package/dist-lib/types/editor/sectionHeaders.d.ts

@@ -0,0 +1,117 @@
+import { lightenHex } from './bannerStyle';
+import type { PageModel } from './store';
+export { lightenHex };
+/** Host-declared description of one canvas section. */
+export interface SectionHeaderDef {
+    /** Section name exactly as the frames carry it — the join key. */
+    section: string;
+    /** Short handle shown large, e.g. "02". */
+    code: string;
+    /** Section title, e.g. "care". */
+    title: string;
+    /** Secondary clause after the title: what kind of group this is. */
+    kind?: string;
+    /** One line a planner needs: what the section covers. */
+    purpose: string;
+    /** Accent colour for the rule and the category pill. */
+    accent: string;
+    /** Category shown in the pill. */
+    pill?: string;
+}
+/**
+ * Words for the facts the core counts. Defaults are English; a host renders
+ * its own language by declaring them, which is how the band stays localized
+ * without the core carrying any copy of its own.
+ */
+export interface SectionHeaderLabels {
+    /** Caption above the code. Default "SECTION". */
+    code?: string;
+    /** Unit for the frame count. Default "frames". */
+    frames?: string;
+    /** Unit for folded state variants. Default "folded". */
+    folded?: string;
+    /** Unit for the scenario count. Default "scenarios". */
+    scenarios?: string;
+    /** Unit for the flow list. Default "flows". */
+    flows?: string;
+}
+export interface SectionHeaderDiagnostic {
+    severity: 'error' | 'warning';
+    section: string;
+    message: string;
+}
+export interface SectionHeaderFacts {
+    /** Every frame that belongs to the section, folded variants included. */
+    frameCount: number;
+    /** Members parked behind a slot holder rather than shown on the canvas. */
+    foldedCount: number;
+    /** Distinct canonical scenario ids among the members. */
+    scenarioCount: number;
+    /** Distinct flows, only worth showing when a section spans more than one. */
+    flows: string[];
+    /** Authored viewport shared by the members, or null when there is no one answer. */
+    viewport: string | null;
+}
+export declare function resolveSectionHeaderLabels(labels: SectionHeaderLabels | undefined): Required<SectionHeaderLabels>;
+export declare function validateSectionHeaders(defs: readonly SectionHeaderDef[], context: {
+    sections: readonly string[];
+}): SectionHeaderDiagnostic[];
+/**
+ * What the core can see about a section without being told. `isShown` marks
+ * the members holding a canvas slot; the rest are folded state variants.
+ */
+export declare function sectionHeaderFacts(pages: readonly PageModel[], options?: {
+    isShown?: (page: PageModel) => boolean;
+}): SectionHeaderFacts;
+/**
+ * The derived line, in the order a reviewer scans it. Facts that would only
+ * repeat the title are left out: a single flow is always the section itself,
+ * and a section with no scenarios has nothing to say about coverage.
+ */
+export declare function sectionHeaderFactLine(facts: SectionHeaderFacts, labels: Required<SectionHeaderLabels>): string;
+export declare const SECTION_HEADER_STYLE: {
+    readonly radius: 12;
+    readonly pillRadius: 999;
+    readonly ruleWidth: 6;
+    readonly gap: 24;
+    readonly paddingY: 20;
+    readonly paddingRight: 32;
+    readonly captionSize: 12;
+    readonly codeSize: 40;
+    readonly titleSize: 32;
+    readonly metaSize: 15;
+    readonly pillSize: 12;
+    readonly pillPaddingY: 6;
+    readonly pillPaddingX: 14;
+    readonly surface: "#343441";
+    readonly pillSurface: "#2e2c3a";
+    readonly caption: "#a1a1b3";
+    readonly code: "#ffffff";
+    readonly title: "#e7e7f0";
+    readonly titleMuted: "#a1a1b3";
+    readonly meta: "#bebecb";
+    readonly purpose: "#c4ccd8";
+};
+/**
+ * Room the band needs above a section box, in canvas units. Sections used to
+ * stack 120px apart with 28px of box padding at each end, leaving 64px — less
+ * than half a band — so the layout reserves this instead. Both the renderer
+ * and the layout read it from here so they cannot drift apart.
+ *
+ * Sized for a purpose line that wraps once at section width; a purpose long
+ * enough to take three lines is an authoring problem, not a layout one.
+ */
+export declare const SECTION_HEADER_RESERVE = 176;
+/**
+ * Widest a band is allowed to be, in canvas units.
+ *
+ * A band spanning its section reached 4333px on the care canvas, which put the
+ * category pill several screens to the right of the code it belongs to — the
+ * identity stopped reading as one object. A banner is a label, so it takes a
+ * measure a reader can take in at once and stops.
+ */
+export declare const SECTION_HEADER_MAX_WIDTH = 1280;
+export declare function setSectionHeaders(defs: readonly SectionHeaderDef[], labels?: SectionHeaderLabels): void;
+export declare function getSectionHeaders(): readonly SectionHeaderDef[];
+export declare function getSectionHeaderLabels(): SectionHeaderLabels | undefined;
+export declare function sectionHeaderFor(section: string): SectionHeaderDef | null;

package/dist-lib/types/editor/shadowPreview.d.ts

@@ -0,0 +1,103 @@
+export interface PreparedShadowPreview {
+    bodyHtml: string;
+    sharedCssText: string;
+    stylesheetLinksHtml: string;
+}
+export interface ShadowPreviewMountInput {
+    /** A complete script-less document snapshot. */
+    snapshot?: string;
+    /** A body fragment to use instead of a complete snapshot. */
+    bodyHtml?: string;
+    /** Common CSS that is pooled with styles extracted from the snapshot. */
+    sharedCssText?: string;
+    /** Content-addressed styles attached independently without frame-level concatenation. */
+    sharedStylesheets?: readonly {
+        key: string;
+        cssText: string;
+    }[];
+    /** Serialized document attributes used by compact body-only artifacts. */
+    htmlAttributes?: string;
+    bodyAttributes?: string;
+    /** External stylesheet links retained by compact body-only artifacts. */
+    stylesheetLinksHtml?: string;
+    /** An optional verified cache identity for sharedCssText. */
+    sharedCssHash?: string;
+    /** A stable channel shared by related previews. */
+    overrideKey?: string;
+    /** CSS that can change without rebuilding or parsing the common stylesheet. */
+    overrideCssText?: string;
+    /** Resolves relative element and CSS resource URLs. */
+    baseUrl?: string;
+}
+export interface ShadowPreviewHandle {
+    readonly root: ShadowRoot;
+    readonly contentElement: HTMLElement;
+    readonly sharedCssHash: string;
+    readonly overrideKey: string;
+    updateBodyHtml(bodyHtml: string, baseUrl?: string): void;
+    updateOverrideCss(cssText: string): void;
+    updateSharedCss(cssText: string): void;
+    teardown(): void;
+}
+export interface ShadowDomMutation {
+    key: string;
+    selector: string;
+    text?: string;
+    textNodeOrdinal?: number;
+    hidden?: boolean;
+    attributes?: Record<string, string | null>;
+    replaceChildrenHtml?: string;
+    staleReason?: string;
+}
+export interface ShadowDomMutationResult {
+    cleanup(): void;
+    issues: string[];
+}
+interface AcquiredStyle {
+    release(): void;
+}
+/** A deterministic content hash suitable for in-memory stylesheet pooling. */
+export declare function hashShadowPreviewCss(cssText: string): string;
+/** Rejects active content before it reaches a live document or ShadowRoot. */
+export declare function assertSafeShadowPreviewMarkup(markup: string): void;
+/**
+ * Splits a safe document snapshot into the lightweight parts needed by a
+ * ShadowRoot. Inline styles become one pooled stylesheet instead of being
+ * repeated in every preview.
+ */
+export declare function prepareShadowPreview(input: Pick<ShadowPreviewMountInput, 'snapshot' | 'bodyHtml' | 'sharedCssText'>): PreparedShadowPreview;
+/** Resolves CSS url() and @import references without touching data/blob/hash URLs. */
+export declare function rebaseShadowPreviewCss(cssText: string, baseUrl: string | undefined): string;
+/**
+ * Applies serializable DOM edits to a frozen preview. The returned cleanup
+ * restores the exact previous DOM state in reverse mutation order.
+ */
+export declare function applyShadowDomMutations(root: ParentNode, mutations: readonly ShadowDomMutation[], options?: {
+    baseUrl?: string;
+}): ShadowDomMutationResult;
+/**
+ * Owns content-addressed common styles and mutable override channels.
+ * Constructable stylesheets are shared by reference. Browsers without them
+ * receive one synchronized style element per mounted root.
+ */
+export declare class ShadowPreviewStylePool {
+    private readonly sharedStyles;
+    private readonly overrideStyles;
+    private acquire;
+    private replaceEntryText;
+    acquireShared(root: ShadowRoot, hash: string, cssText: string): AcquiredStyle;
+    acquireSharedMany(root: ShadowRoot, styles: readonly {
+        key: string;
+        cssText: string;
+    }[]): AcquiredStyle;
+    acquireOverride(root: ShadowRoot, key: string, cssText: string): AcquiredStyle;
+    /** Updates every root using this shared style without rebuilding its DOM. */
+    updateSharedCss(hash: string, cssText: string): boolean;
+    /** Updates every mounted preview subscribed to the same override channel. */
+    updateOverrideCss(key: string, cssText: string): boolean;
+    dispose(): void;
+}
+export declare const defaultShadowPreviewStylePool: ShadowPreviewStylePool;
+/** Mounts a script-less, non-interactive preview with pooled common styles. */
+export declare function mountFrozenShadowPreview(host: HTMLElement, input: ShadowPreviewMountInput, stylePool?: ShadowPreviewStylePool): ShadowPreviewHandle;
+export {};

package/dist-lib/types/editor/sharedSource.d.ts

@@ -0,0 +1,40 @@
+import type { NodeModel, PageModel } from './store';
+/**
+ * The smallest unit that connects DOMs rendered multiple times from one source.
+ * - Within the registry component, importPath is used as scope.
+ * - Other screen DOMs use structural paths within the same route.
+ * - If the editing range is shared, not only the style but also text/props/visibility are the same.
+ * It is immediately reflected in all source instances.
+ * - When the runtime state needs to be maintained for each screen, the user selects the instance range.
+ */
+export declare const SHARED_SOURCE_PATCH_KEYS: readonly ["type", "widthMode", "width", "heightMode", "height", "gap", "padding", "justify", "alignItems", "fill", "radius", "borderWidth", "borderColor", "opacity", "fontSize", "fontWeight", "color", "textAlign", "hidden", "text", "componentName", "componentProps", "childrenText", "domAttributes", "domStyle"];
+export type SharedSourcePatchKey = (typeof SHARED_SOURCE_PATCH_KEYS)[number];
+export type SharedSourcePatch = Partial<Pick<NodeModel, SharedSourcePatchKey>>;
+export type SharedSourceEditScope = 'shared' | 'instance';
+export interface SharedSourceFrameSummary {
+    id: string;
+    name: string;
+}
+export interface SharedSourceImpact {
+    sourceKey: string;
+    frames: SharedSourceFrameSummary[];
+    nodeCount: number;
+}
+/** In the edit patch, copy only fields that can be safely shared in the actual source style. */
+export declare function pickSharedSourcePatch(partial: Partial<NodeModel>): SharedSourcePatch;
+export declare function cloneSharedSourcePatch(patch: SharedSourcePatch): SharedSourcePatch;
+export declare function hasSharedSourcePatch(patch: SharedSourcePatch): boolean;
+/** A safe CSS representation of a shared patch that can be immediately injected into a frozen DOM preview. */
+export declare function sharedSourcePatchCssDeclarations(patch: SharedSourcePatch): Record<string, string>;
+/** Page-only fallback scope. When a component scope is found, it is replaced in the corresponding subtree. */
+export declare function sharedPageScope(page: Pick<PageModel, 'id' | 'route' | 'sourcePaths' | 'importPageId'>): string;
+/**
+ * Provides a reproducible sourceKey to the DOM tree.
+ * Do not globally connect with the same tag/testid and be sure to
+ * Includes component/page scope + parent structure path + identical sibling occurrences.
+ */
+export declare function bindSharedSourceTree(root: NodeModel, page: PageModel): void;
+export declare function visitSourceNodes(root: NodeModel, visit: (node: NodeModel) => void): void;
+/** How many frames and layers the sourceKey actually connects to. Used to display the UI influence range. */
+export declare function sharedSourceImpact(pages: readonly PageModel[], sourceKey: string): SharedSourceImpact;
+export declare function applySharedSourceOverrides(root: NodeModel, overrides: ReadonlyMap<string, SharedSourcePatch>): void;

package/dist-lib/types/editor/sourceJournal.d.ts

@@ -0,0 +1,27 @@
+import type { InspectApplyPayload, SourceEditScope, SourceIdentity } from './inspect';
+import type { NodeModel, PageModel } from './store';
+type JournalNode = Pick<NodeModel, 'id' | 'type' | 'children' | 'domAttributes' | 'sourceStyle' | 'text' | 'gap' | 'padding' | 'justify' | 'alignItems' | 'fill' | 'radius' | 'borderWidth' | 'borderColor' | 'opacity' | 'fontSize' | 'fontWeight' | 'color' | 'textAlign' | 'domStyle' | 'sourceProps'>;
+type JournalPage = Pick<PageModel, 'id' | 'importPageId' | 'name' | 'root'>;
+type ParseSourceIdentity = (raw: string | null | undefined) => SourceIdentity | null;
+export interface SourceJournalSnapshot {
+    revision: number;
+    payload: InspectApplyPayload;
+}
+/**
+ * A source-backed baseline journal in a regular canvas patch.
+ * The baseline is maintained even after ack, so undo appears again as a reverse source change.
+ */
+export declare class SourcePatchJournal {
+    private baselines;
+    private parseIdentity;
+    revision: number;
+    constructor(parseIdentity: ParseSourceIdentity);
+    captureBefore(pages: readonly JournalPage[], nodeId: string, partial: Partial<JournalNode>): boolean;
+    markContextChanged(): void;
+    /** After restoring the canvas based on the last reflection standard, the remaining pending baselines are also discarded. */
+    discard(): void;
+    markModelRestored(): void;
+    snapshot(pages: readonly JournalPage[], scopeForNode: (nodeId: string, identity: SourceIdentity) => SourceEditScope): SourceJournalSnapshot;
+    ack(expectedRevision: number, pages: readonly JournalPage[], scopeForNode: (nodeId: string, identity: SourceIdentity) => SourceEditScope): boolean;
+}
+export {};