@tscaps/engine 0.1.1 → 0.2.1

package/README.md

@@ -1,10 +1,8 @@
 # @tscaps/engine
 
-> Burn subtitles into video in the browser. No server, no editor.
+A TypeScript engine that adds captions to a video and burns them in — all in the browser, no server involved. It sources captions (in-browser Whisper transcription, an existing `.srt`, or a hand-built `Document`), lays them out through CSS, and exports the result frame-by-frame to a new video.
 
-`@tscaps/engine` is a TypeScript engine that takes a video file, sources its captions (in-browser Whisper transcription, an existing `.srt`, or a hand-built `Document`), lays them out through CSS, and exports the result frame-by-frame to a new video — all client-side, with no backend involved.
-
-The defining technical bet: **CSS is the rendering engine**. Subtitle preview is a DOM overlay above a `<video>` element. Final export samples that same CSS-styled DOM into bitmaps per frame, composited by a browser-side video pipeline. One visual artifact, two rendering paths.
+Captions are HTML elements styled with CSS. On export, the engine rasterizes that DOM at each frame's timestamp into a bitmap and composites it with the video frame. The browser renders the captions.
 
 ## Install
 

package/dist/modules/css/CssScoper.d.ts

@@ -5,12 +5,32 @@
  * scope-unique form and the matching `animation-name` / `animation`
  * shorthand references in the same stylesheet are rewritten in step.
  *
+ * Selectors inside conditional at-rule bodies (`@container`, `@media`,
+ * `@supports`, `@layer`, `@scope`) are scoped recursively — without
+ * this, a rule like `@container … { .foo { … } }` would emit unscoped
+ * `.foo` and lose to the top-level scoped version on specificity.
+ *
  * `scopeSelector` is expected to be a simple class selector
  * (e.g. `.my-scope`); its identifier portion seeds the keyframe rename.
  */
 export declare class CssScoper {
     scope(css: string, scopeSelector: string): string;
     private scopeKeyframes;
-    private scopeSelectors;
+    private scopeSelectorsInRange;
+    private scopeAtRuleBody;
+    private scopeCompoundSelector;
+    private isWhitespace;
+    private isCommentStart;
+    private findCommentEnd;
+    private findBraceOrEnd;
+    private isAtRuleHeader;
+    private extractAtRuleName;
+    /**
+     * Returns the index of the `}` that closes the block opened just
+     * before `start`. Respects string literals and CSS comments so that
+     * `{`/`}` characters appearing inside them don't shift the depth.
+     * Falls back to `stopAt` if the block is unterminated within range.
+     */
+    private findMatchingClose;
 }
 //# sourceMappingURL=CssScoper.d.ts.map

package/dist/modules/css/CssScoper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CssScoper.d.ts","sourceRoot":"","sources":["../../../src/modules/css/CssScoper.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,qBAAa,SAAS;IACpB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IAKjD,OAAO,CAAC,cAAc;IA2BtB,OAAO,CAAC,cAAc;CA0DvB"}
+{"version":3,"file":"CssScoper.d.ts","sourceRoot":"","sources":["../../../src/modules/css/CssScoper.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS;IACpB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IAKjD,OAAO,CAAC,cAAc;IA2BtB,OAAO,CAAC,qBAAqB;IAuC7B,OAAO,CAAC,eAAe;IAcvB,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,iBAAiB;IAKzB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;CAyB1B"}

package/dist/modules/css/CssScoper.js

@@ -1,5 +1,15 @@
 const KEYFRAME_NAME_RE = /@(?:-webkit-|-moz-)?keyframes\s+([a-zA-Z_-][a-zA-Z0-9_-]*)/g;
-const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const AT_RULE_NAME_RE = /^@([a-zA-Z][a-zA-Z0-9-]*)/;
+const SELECTOR_SPECIAL_CHARS_RE = /[.*+?^${}()|[\]\\]/g;
+/** At-rules whose body holds regular style rules — selectors inside must be scoped. */
+const SCOPEABLE_AT_RULES = new Set([
+    'container',
+    'media',
+    'supports',
+    'layer',
+    'scope',
+]);
+const escapeRegex = (s) => s.replace(SELECTOR_SPECIAL_CHARS_RE, '\\$&');
 /**
  * Scopes a CSS string so it can coexist with sibling stylesheets in
  * the same document. Top-level selectors get prefixed with
@@ -7,13 +17,18 @@ const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  * scope-unique form and the matching `animation-name` / `animation`
  * shorthand references in the same stylesheet are rewritten in step.
  *
+ * Selectors inside conditional at-rule bodies (`@container`, `@media`,
+ * `@supports`, `@layer`, `@scope`) are scoped recursively — without
+ * this, a rule like `@container … { .foo { … } }` would emit unscoped
+ * `.foo` and lose to the top-level scoped version on specificity.
+ *
  * `scopeSelector` is expected to be a simple class selector
  * (e.g. `.my-scope`); its identifier portion seeds the keyframe rename.
  */
 export class CssScoper {
     scope(css, scopeSelector) {
         const scopeKey = scopeSelector.replace(/^\.+/, '');
-        return this.scopeSelectors(this.scopeKeyframes(css, scopeKey), scopeSelector);
+        return this.scopeSelectorsInRange(this.scopeKeyframes(css, scopeKey), 0, undefined, scopeSelector);
     }
     scopeKeyframes(css, scopeKey) {
         const names = new Set();
@@ -39,71 +54,129 @@ export class CssScoper {
         }
         return result;
     }
-    scopeSelectors(css, scopeSelector) {
+    scopeSelectorsInRange(css, start, end, scopeSelector) {
+        const stopAt = end ?? css.length;
         let result = '';
-        let i = 0;
-        let depth = 0;
-        while (i < css.length) {
-            if (css[i] === '{') {
-                depth++;
-                result += '{';
+        let i = start;
+        while (i < stopAt) {
+            const ch = css[i];
+            if (this.isWhitespace(ch)) {
+                result += ch;
                 i++;
+                continue;
             }
-            else if (css[i] === '}') {
-                depth--;
+            if (this.isCommentStart(css, i)) {
+                const commentEnd = this.findCommentEnd(css, i, stopAt);
+                result += css.slice(i, commentEnd);
+                i = commentEnd;
+                continue;
+            }
+            const braceIndex = this.findBraceOrEnd(css, i, stopAt);
+            if (braceIndex === stopAt) {
+                result += css.slice(i, stopAt);
+                return result;
+            }
+            const header = css.slice(i, braceIndex);
+            const bodyStart = braceIndex + 1;
+            const bodyEnd = this.findMatchingClose(css, bodyStart, stopAt);
+            if (this.isAtRuleHeader(header)) {
+                result += `${header}{`;
+                result += this.scopeAtRuleBody(css, bodyStart, bodyEnd, header, scopeSelector);
                 result += '}';
-                i++;
             }
-            else if (depth === 0) {
-                const remaining = css.slice(i);
-                const ws = remaining.match(/^\s+/);
-                if (ws) {
-                    result += ws[0];
-                    i += ws[0].length;
-                    continue;
-                }
-                // Top-level comments — copy through. Without this, a comment placed
-                // before an @-rule (e.g. `/* note */ @keyframes foo`) would be
-                // swallowed into the regular-selector branch and fed to the scoper
-                // alongside the @-rule header, producing invalid CSS that drops the
-                // whole rule.
-                if (remaining.startsWith('/*')) {
-                    const end = remaining.indexOf('*/');
-                    if (end === -1) {
-                        result += remaining;
-                        break;
-                    }
-                    result += remaining.slice(0, end + 2);
-                    i += end + 2;
+            else {
+                result += `${this.scopeCompoundSelector(header, scopeSelector)} {`;
+                result += css.slice(bodyStart, bodyEnd);
+                result += '}';
+            }
+            i = bodyEnd + 1;
+        }
+        return result;
+    }
+    scopeAtRuleBody(css, bodyStart, bodyEnd, header, scopeSelector) {
+        const name = this.extractAtRuleName(header);
+        if (SCOPEABLE_AT_RULES.has(name)) {
+            return this.scopeSelectorsInRange(css, bodyStart, bodyEnd, scopeSelector);
+        }
+        return css.slice(bodyStart, bodyEnd);
+    }
+    scopeCompoundSelector(selector, scopeSelector) {
+        return selector
+            .trim()
+            .split(',')
+            .map((s) => `${scopeSelector} ${s.trim()}`)
+            .join(', ');
+    }
+    isWhitespace(ch) {
+        return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r' || ch === '\f';
+    }
+    isCommentStart(css, i) {
+        return css[i] === '/' && css[i + 1] === '*';
+    }
+    findCommentEnd(css, commentStart, stopAt) {
+        const closeIndex = css.indexOf('*/', commentStart + 2);
+        return closeIndex === -1 || closeIndex >= stopAt ? stopAt : closeIndex + 2;
+    }
+    findBraceOrEnd(css, start, stopAt) {
+        for (let i = start; i < stopAt; i++) {
+            if (css[i] === '{')
+                return i;
+        }
+        return stopAt;
+    }
+    isAtRuleHeader(header) {
+        return header.trimStart().startsWith('@');
+    }
+    extractAtRuleName(header) {
+        const match = header.trimStart().match(AT_RULE_NAME_RE);
+        return match ? match[1].toLowerCase() : '';
+    }
+    /**
+     * Returns the index of the `}` that closes the block opened just
+     * before `start`. Respects string literals and CSS comments so that
+     * `{`/`}` characters appearing inside them don't shift the depth.
+     * Falls back to `stopAt` if the block is unterminated within range.
+     */
+    findMatchingClose(css, start, stopAt) {
+        let depth = 1;
+        let i = start;
+        let stringDelim = null;
+        while (i < stopAt) {
+            const ch = css[i];
+            if (stringDelim) {
+                if (ch === '\\' && i + 1 < stopAt) {
+                    i += 2;
                     continue;
                 }
-                const brace = remaining.indexOf('{');
-                if (brace === -1) {
-                    result += remaining;
-                    break;
-                }
-                if (remaining.startsWith('@')) {
-                    result += remaining.slice(0, brace + 1);
-                    i += brace + 1;
-                    depth++;
-                }
-                else {
-                    const selector = remaining.slice(0, brace).trim();
-                    const scoped = selector
-                        .split(',')
-                        .map(s => `${scopeSelector} ${s.trim()}`)
-                        .join(', ');
-                    result += `${scoped} {`;
-                    i += brace + 1;
-                    depth++;
-                }
+                if (ch === stringDelim)
+                    stringDelim = null;
+                i++;
+                continue;
             }
-            else {
-                result += css[i];
+            if (ch === '"' || ch === '\'') {
+                stringDelim = ch;
+                i++;
+                continue;
+            }
+            if (this.isCommentStart(css, i)) {
+                i = this.findCommentEnd(css, i, stopAt);
+                continue;
+            }
+            if (ch === '{') {
+                depth++;
                 i++;
+                continue;
             }
+            if (ch === '}') {
+                depth--;
+                if (depth === 0)
+                    return i;
+                i++;
+                continue;
+            }
+            i++;
         }
-        return result;
+        return stopAt;
     }
 }
 //# sourceMappingURL=CssScoper.js.map

package/dist/modules/css/CssScoper.js.map

@@ -1 +1 @@
-{"version":3,"file":"CssScoper.js","sourceRoot":"","sources":["../../../src/modules/css/CssScoper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CssScoper.js","sourceRoot":"","sources":["../../../src/modules/css/CssScoper.ts"],"names":[],"mappings":"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"}

package/dist/modules/css/CssVarReferenceScanner.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns every CSS custom property name referenced via `var(--name)`
+ * anywhere in the given source.
+ *
+ * Cheap regex scan rather than a CSS parse. False positives are
+ * limited to literal `var(--…)` substrings inside string values; pass
+ * the source through {@link CssMinifier} first to drop comments that
+ * would otherwise contribute to the result.
+ */
+export declare class CssVarReferenceScanner {
+    scan(css: string): Set<string>;
+}
+//# sourceMappingURL=CssVarReferenceScanner.d.ts.map

package/dist/modules/css/CssVarReferenceScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CssVarReferenceScanner.d.ts","sourceRoot":"","sources":["../../../src/modules/css/CssVarReferenceScanner.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,qBAAa,sBAAsB;IAEjC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;CAO/B"}

package/dist/modules/css/CssVarReferenceScanner.js

@@ -0,0 +1,20 @@
+const VAR_REFERENCE_PATTERN = /var\(\s*(--[a-zA-Z0-9_-]+)/g;
+/**
+ * Returns every CSS custom property name referenced via `var(--name)`
+ * anywhere in the given source.
+ *
+ * Cheap regex scan rather than a CSS parse. False positives are
+ * limited to literal `var(--…)` substrings inside string values; pass
+ * the source through {@link CssMinifier} first to drop comments that
+ * would otherwise contribute to the result.
+ */
+export class CssVarReferenceScanner {
+    scan(css) {
+        const found = new Set();
+        for (const match of css.matchAll(VAR_REFERENCE_PATTERN)) {
+            found.add(match[1]);
+        }
+        return found;
+    }
+}
+//# sourceMappingURL=CssVarReferenceScanner.js.map

package/dist/modules/css/CssVarReferenceScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CssVarReferenceScanner.js","sourceRoot":"","sources":["../../../src/modules/css/CssVarReferenceScanner.ts"],"names":[],"mappings":"AAAA,MAAM,qBAAqB,GAAG,6BAA6B,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,OAAO,sBAAsB;IAEjC,IAAI,CAAC,GAAW;QACd,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;QAChC,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;YACxD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;QACvB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/modules/css/index.d.ts

@@ -3,4 +3,5 @@ export { BrowserCssResourceEmbedder } from '../css/BrowserCssResourceEmbedder';
 export { NoopCssResourceEmbedder } from '../css/NoopCssResourceEmbedder';
 export { CssScoper } from '../css/CssScoper';
 export { CssMinifier } from '../css/CssMinifier';
+export { CssVarReferenceScanner } from '../css/CssVarReferenceScanner';
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/css/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/css/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/css/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/modules/css/index.js

@@ -2,4 +2,5 @@ export { BrowserCssResourceEmbedder } from '../css/BrowserCssResourceEmbedder';
 export { NoopCssResourceEmbedder } from '../css/NoopCssResourceEmbedder';
 export { CssScoper } from '../css/CssScoper';
 export { CssMinifier } from '../css/CssMinifier';
+export { CssVarReferenceScanner } from '../css/CssVarReferenceScanner';
 //# sourceMappingURL=index.js.map

package/dist/modules/css/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/css/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/css/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/modules/document/CssVariable.d.ts

@@ -1,6 +1,12 @@
 /**
- * CSS custom properties exposed on each rendered node so consumers can
- * react to playback timing.
+ * CSS custom properties published on the rendered subtree so the
+ * consumer's stylesheet can react to playback timing and node
+ * structure, plus a small set the consumer writes back so the engine's
+ * baseline rules pick up per-sheet overrides.
+ *
+ * Each entry is owned by whichever side **writes** it; once published,
+ * any reader (engine baseline CSS, consumer template CSS, JS
+ * inspection) can pick it up.
  *
  * Naming:
  *  - `--on-<x>-starts` / `--on-<x>-ends` are *event timestamps*: they
@@ -9,6 +15,8 @@
  *    the past.
  *  - `--<x>-duration` is a *span*, not an event. It does not coincide
  *    with any moment, so it carries no `on-` prefix.
+ *  - Structural metadata (letter index, character count, …) carries no
+ *    `on-` prefix either — those are not events.
  */
 export declare enum CssVariable {
     SECTION_STARTS = "--on-section-starts",
@@ -17,6 +25,8 @@ export declare enum CssVariable {
     SEGMENT_STARTS = "--on-segment-starts",
     SEGMENT_ENDS = "--on-segment-ends",
     SEGMENT_DURATION = "--segment-duration",
+    SEGMENT_CHAR_COUNT = "--segment-char-count",
+    SEGMENT_INDEX = "--segment-index",
     LINE_NOT_NARRATED_YET_STARTS = "--on-line-not-narrated-yet-starts",
     LINE_NOT_NARRATED_YET_ENDS = "--on-line-not-narrated-yet-ends",
     LINE_NOT_NARRATED_YET_DURATION = "--line-not-narrated-yet-duration",
@@ -37,10 +47,21 @@ export declare enum CssVariable {
     WORD_ALREADY_NARRATED_DURATION = "--word-already-narrated-duration",
     LETTER_INDEX = "--letter-index",
     LETTER_COUNT = "--letter-count",
+    WORD_INDEX = "--word-index",
+    WORD_CHAR_COUNT = "--word-char-count",
+    WORD_COUNT = "--word-count",
+    LAST_WORD_CHAR_COUNT = "--last-word-char-count",
     VIDEO_FRAME = "--video-frame",
     SUBTITLE_REGION_WIDTH = "--subtitle-region-width",
     SUBTITLE_REGION_HEIGHT = "--subtitle-region-height",
     SUBTITLE_REGION_X = "--subtitle-region-x",
-    SUBTITLE_REGION_Y = "--subtitle-region-y"
+    SUBTITLE_REGION_Y = "--subtitle-region-y",
+    SEGMENT_PADDING_TOP = "--segment-padding-top",
+    SEGMENT_PADDING_BOTTOM = "--segment-padding-bottom",
+    BEHIND_ACTOR_SCENE_VALID = "--behind-actor-scene-valid",
+    BEHIND_ACTOR_FORCED = "--behind-actor-forced",
+    BEHIND_ACTOR_ACTIVE = "--behind-actor-active",
+    DECORATION_FONT_SIZE_MULTIPLIER = "--decoration-font-size-multiplier",
+    DECORATION_GAP_MULTIPLIER = "--decoration-gap-multiplier"
 }
 //# sourceMappingURL=CssVariable.d.ts.map

package/dist/modules/document/CssVariable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CssVariable.d.ts","sourceRoot":"","sources":["../../../src/modules/document/CssVariable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,oBAAY,WAAW;IACrB,cAAc,wBAAwB;IACtC,YAAY,sBAAsB;IAClC,gBAAgB,uBAAuB;IAEvC,cAAc,wBAAwB;IACtC,YAAY,sBAAsB;IAClC,gBAAgB,uBAAuB;IAEvC,4BAA4B,sCAAsC;IAClE,0BAA0B,oCAAoC;IAC9D,8BAA8B,qCAAqC;IACnE,0BAA0B,oCAAoC;IAC9D,wBAAwB,kCAAkC;IAC1D,4BAA4B,mCAAmC;IAC/D,4BAA4B,sCAAsC;IAClE,0BAA0B,oCAAoC;IAC9D,8BAA8B,qCAAqC;IAEnE,4BAA4B,sCAAsC;IAClE,0BAA0B,oCAAoC;IAC9D,8BAA8B,qCAAqC;IACnE,0BAA0B,oCAAoC;IAC9D,wBAAwB,kCAAkC;IAC1D,4BAA4B,mCAAmC;IAC/D,4BAA4B,sCAAsC;IAClE,0BAA0B,oCAAoC;IAC9D,8BAA8B,qCAAqC;IAEnE,YAAY,mBAAmB;IAC/B,YAAY,mBAAmB;IAE/B,WAAW,kBAAkB;IAC7B,qBAAqB,4BAA4B;IACjD,sBAAsB,6BAA6B;IACnD,iBAAiB,wBAAwB;IACzC,iBAAiB,wBAAwB;CAC1C"}
+{"version":3,"file":"CssVariable.d.ts","sourceRoot":"","sources":["../../../src/modules/document/CssVariable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oBAAY,WAAW;IAMrB,cAAc,wBAAwB;IACtC,YAAY,sBAAsB;IAClC,gBAAgB,uBAAuB;IAEvC,cAAc,wBAAwB;IACtC,YAAY,sBAAsB;IAClC,gBAAgB,uBAAuB;IACvC,kBAAkB,yBAAyB;IAC3C,aAAa,oBAAoB;IAEjC,4BAA4B,sCAAsC;IAClE,0BAA0B,oCAAoC;IAC9D,8BAA8B,qCAAqC;IACnE,0BAA0B,oCAAoC;IAC9D,wBAAwB,kCAAkC;IAC1D,4BAA4B,mCAAmC;IAC/D,4BAA4B,sCAAsC;IAClE,0BAA0B,oCAAoC;IAC9D,8BAA8B,qCAAqC;IAEnE,4BAA4B,sCAAsC;IAClE,0BAA0B,oCAAoC;IAC9D,8BAA8B,qCAAqC;IACnE,0BAA0B,oCAAoC;IAC9D,wBAAwB,kCAAkC;IAC1D,4BAA4B,mCAAmC;IAC/D,4BAA4B,sCAAsC;IAClE,0BAA0B,oCAAoC;IAC9D,8BAA8B,qCAAqC;IAEnE,YAAY,mBAAmB;IAC/B,YAAY,mBAAmB;IAE/B,UAAU,iBAAiB;IAC3B,eAAe,sBAAsB;IACrC,UAAU,iBAAiB;IAC3B,oBAAoB,2BAA2B;IAE/C,WAAW,kBAAkB;IAC7B,qBAAqB,4BAA4B;IACjD,sBAAsB,6BAA6B;IACnD,iBAAiB,wBAAwB;IACzC,iBAAiB,wBAAwB;IAEzC,mBAAmB,0BAA0B;IAC7C,sBAAsB,6BAA6B;IAEnD,wBAAwB,+BAA+B;IACvD,mBAAmB,0BAA0B;IAC7C,mBAAmB,0BAA0B;IAM7C,+BAA+B,sCAAsC;IACrE,yBAAyB,gCAAgC;CAC1D"}

package/dist/modules/document/CssVariable.js

@@ -1,6 +1,12 @@
 /**
- * CSS custom properties exposed on each rendered node so consumers can
- * react to playback timing.
+ * CSS custom properties published on the rendered subtree so the
+ * consumer's stylesheet can react to playback timing and node
+ * structure, plus a small set the consumer writes back so the engine's
+ * baseline rules pick up per-sheet overrides.
+ *
+ * Each entry is owned by whichever side **writes** it; once published,
+ * any reader (engine baseline CSS, consumer template CSS, JS
+ * inspection) can pick it up.
  *
  * Naming:
  *  - `--on-<x>-starts` / `--on-<x>-ends` are *event timestamps*: they
@@ -9,15 +15,23 @@
  *    the past.
  *  - `--<x>-duration` is a *span*, not an event. It does not coincide
  *    with any moment, so it carries no `on-` prefix.
+ *  - Structural metadata (letter index, character count, …) carries no
+ *    `on-` prefix either — those are not events.
  */
 export var CssVariable;
 (function (CssVariable) {
+    // ── Engine-written ─────────────────────────────────────────────
+    // Published by the engine on every render. The consumer's
+    // stylesheet reads them through `var(...)` to drive animations,
+    // pick up structural metadata, or paint the video frame.
     CssVariable["SECTION_STARTS"] = "--on-section-starts";
     CssVariable["SECTION_ENDS"] = "--on-section-ends";
     CssVariable["SECTION_DURATION"] = "--section-duration";
     CssVariable["SEGMENT_STARTS"] = "--on-segment-starts";
     CssVariable["SEGMENT_ENDS"] = "--on-segment-ends";
     CssVariable["SEGMENT_DURATION"] = "--segment-duration";
+    CssVariable["SEGMENT_CHAR_COUNT"] = "--segment-char-count";
+    CssVariable["SEGMENT_INDEX"] = "--segment-index";
     CssVariable["LINE_NOT_NARRATED_YET_STARTS"] = "--on-line-not-narrated-yet-starts";
     CssVariable["LINE_NOT_NARRATED_YET_ENDS"] = "--on-line-not-narrated-yet-ends";
     CssVariable["LINE_NOT_NARRATED_YET_DURATION"] = "--line-not-narrated-yet-duration";
@@ -38,10 +52,24 @@ export var CssVariable;
     CssVariable["WORD_ALREADY_NARRATED_DURATION"] = "--word-already-narrated-duration";
     CssVariable["LETTER_INDEX"] = "--letter-index";
     CssVariable["LETTER_COUNT"] = "--letter-count";
+    CssVariable["WORD_INDEX"] = "--word-index";
+    CssVariable["WORD_CHAR_COUNT"] = "--word-char-count";
+    CssVariable["WORD_COUNT"] = "--word-count";
+    CssVariable["LAST_WORD_CHAR_COUNT"] = "--last-word-char-count";
     CssVariable["VIDEO_FRAME"] = "--video-frame";
     CssVariable["SUBTITLE_REGION_WIDTH"] = "--subtitle-region-width";
     CssVariable["SUBTITLE_REGION_HEIGHT"] = "--subtitle-region-height";
     CssVariable["SUBTITLE_REGION_X"] = "--subtitle-region-x";
     CssVariable["SUBTITLE_REGION_Y"] = "--subtitle-region-y";
+    CssVariable["SEGMENT_PADDING_TOP"] = "--segment-padding-top";
+    CssVariable["SEGMENT_PADDING_BOTTOM"] = "--segment-padding-bottom";
+    CssVariable["BEHIND_ACTOR_SCENE_VALID"] = "--behind-actor-scene-valid";
+    CssVariable["BEHIND_ACTOR_FORCED"] = "--behind-actor-forced";
+    CssVariable["BEHIND_ACTOR_ACTIVE"] = "--behind-actor-active";
+    // ── Consumer-written ───────────────────────────────────────────
+    // The engine's baseline CSS reads these with sensible defaults;
+    // the consumer sets them per-sheet to override the default.
+    CssVariable["DECORATION_FONT_SIZE_MULTIPLIER"] = "--decoration-font-size-multiplier";
+    CssVariable["DECORATION_GAP_MULTIPLIER"] = "--decoration-gap-multiplier";
 })(CssVariable || (CssVariable = {}));
 //# sourceMappingURL=CssVariable.js.map

package/dist/modules/document/CssVariable.js.map

@@ -1 +1 @@
-{"version":3,"file":"CssVariable.js","sourceRoot":"","sources":["../../../src/modules/document/CssVariable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,WAqCX;AArCD,WAAY,WAAW;IACrB,qDAAsC,CAAA;IACtC,iDAAkC,CAAA;IAClC,sDAAuC,CAAA;IAEvC,qDAAsC,CAAA;IACtC,iDAAkC,CAAA;IAClC,sDAAuC,CAAA;IAEvC,iFAAkE,CAAA;IAClE,6EAA8D,CAAA;IAC9D,kFAAmE,CAAA;IACnE,6EAA8D,CAAA;IAC9D,yEAA0D,CAAA;IAC1D,8EAA+D,CAAA;IAC/D,iFAAkE,CAAA;IAClE,6EAA8D,CAAA;IAC9D,kFAAmE,CAAA;IAEnE,iFAAkE,CAAA;IAClE,6EAA8D,CAAA;IAC9D,kFAAmE,CAAA;IACnE,6EAA8D,CAAA;IAC9D,yEAA0D,CAAA;IAC1D,8EAA+D,CAAA;IAC/D,iFAAkE,CAAA;IAClE,6EAA8D,CAAA;IAC9D,kFAAmE,CAAA;IAEnE,8CAA+B,CAAA;IAC/B,8CAA+B,CAAA;IAE/B,4CAA6B,CAAA;IAC7B,gEAAiD,CAAA;IACjD,kEAAmD,CAAA;IACnD,wDAAyC,CAAA;IACzC,wDAAyC,CAAA;AAC3C,CAAC,EArCW,WAAW,KAAX,WAAW,QAqCtB"}
+{"version":3,"file":"CssVariable.js","sourceRoot":"","sources":["../../../src/modules/document/CssVariable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAN,IAAY,WA+DX;AA/DD,WAAY,WAAW;IACrB,kEAAkE;IAClE,0DAA0D;IAC1D,gEAAgE;IAChE,yDAAyD;IAEzD,qDAAsC,CAAA;IACtC,iDAAkC,CAAA;IAClC,sDAAuC,CAAA;IAEvC,qDAAsC,CAAA;IACtC,iDAAkC,CAAA;IAClC,sDAAuC,CAAA;IACvC,0DAA2C,CAAA;IAC3C,gDAAiC,CAAA;IAEjC,iFAAkE,CAAA;IAClE,6EAA8D,CAAA;IAC9D,kFAAmE,CAAA;IACnE,6EAA8D,CAAA;IAC9D,yEAA0D,CAAA;IAC1D,8EAA+D,CAAA;IAC/D,iFAAkE,CAAA;IAClE,6EAA8D,CAAA;IAC9D,kFAAmE,CAAA;IAEnE,iFAAkE,CAAA;IAClE,6EAA8D,CAAA;IAC9D,kFAAmE,CAAA;IACnE,6EAA8D,CAAA;IAC9D,yEAA0D,CAAA;IAC1D,8EAA+D,CAAA;IAC/D,iFAAkE,CAAA;IAClE,6EAA8D,CAAA;IAC9D,kFAAmE,CAAA;IAEnE,8CAA+B,CAAA;IAC/B,8CAA+B,CAAA;IAE/B,0CAA2B,CAAA;IAC3B,oDAAqC,CAAA;IACrC,0CAA2B,CAAA;IAC3B,8DAA+C,CAAA;IAE/C,4CAA6B,CAAA;IAC7B,gEAAiD,CAAA;IACjD,kEAAmD,CAAA;IACnD,wDAAyC,CAAA;IACzC,wDAAyC,CAAA;IAEzC,4DAA6C,CAAA;IAC7C,kEAAmD,CAAA;IAEnD,sEAAuD,CAAA;IACvD,4DAA6C,CAAA;IAC7C,4DAA6C,CAAA;IAE7C,kEAAkE;IAClE,gEAAgE;IAChE,4DAA4D;IAE5D,oFAAqE,CAAA;IACrE,wEAAyD,CAAA;AAC3D,CAAC,EA/DW,WAAW,KAAX,WAAW,QA+DtB"}

package/dist/modules/document/Decoration.d.ts

@@ -0,0 +1,42 @@
+import { TimeFragment } from '../document/TimeFragment';
+export interface DecorationProps {
+    readonly id: string;
+    readonly glyph: string;
+    /** Effective time window. When `null`, callers fall back to the host word's time. */
+    readonly customTime?: TimeFragment | null | undefined;
+    /**
+     * Trailing text rendered next to the glyph, outside the decoration's
+     * own style scope so it inherits the host word's typography.
+     */
+    readonly trail?: string | undefined;
+}
+/**
+ * Render-time context the decoration needs from its ancestors. The
+ * owning segment's window and the host word's window are supplied by
+ * whoever iterates the tree.
+ */
+export interface DecorationRenderContext {
+    readonly segTime: TimeFragment;
+    readonly wordTime: TimeFragment;
+}
+/**
+ * A non-textual glyph attached to a word. Carries its own id so it can
+ * be addressed as an independent target for per-element overrides
+ * (size, position, rotation) and interaction bindings without becoming
+ * a separate Word in the document hierarchy.
+ *
+ * The id is opaque; callers pick an encoding stable across document
+ * re-derivation.
+ */
+export declare class Decoration {
+    static readonly CSS_CLASS = "word-decoration";
+    readonly id: string;
+    readonly glyph: string;
+    readonly customTime: TimeFragment | null;
+    readonly trail: string;
+    constructor(props: DecorationProps);
+    /** The `--on-word-*` time variables driven by this decoration's effective time. Falls back to `ctx.wordTime` when no `customTime` is set. */
+    getCssVariables(currentTime: number, ctx: DecorationRenderContext): Record<string, string>;
+    with(changes: Partial<DecorationProps>): Decoration;
+}
+//# sourceMappingURL=Decoration.d.ts.map

package/dist/modules/document/Decoration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decoration.d.ts","sourceRoot":"","sources":["../../../src/modules/document/Decoration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAG9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,CAAC;IACtD;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,SAAS,qBAAqB;IAE9C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,KAAK,EAAE,eAAe;IAOlC,6IAA6I;IAC7I,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAqB1F,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU;CASpD"}

package/dist/modules/document/Decoration.js

@@ -0,0 +1,52 @@
+import { CssVariable } from '../document/CssVariable';
+/**
+ * A non-textual glyph attached to a word. Carries its own id so it can
+ * be addressed as an independent target for per-element overrides
+ * (size, position, rotation) and interaction bindings without becoming
+ * a separate Word in the document hierarchy.
+ *
+ * The id is opaque; callers pick an encoding stable across document
+ * re-derivation.
+ */
+export class Decoration {
+    static CSS_CLASS = 'word-decoration';
+    id;
+    glyph;
+    customTime;
+    trail;
+    constructor(props) {
+        this.id = props.id;
+        this.glyph = props.glyph;
+        this.customTime = props.customTime ?? null;
+        this.trail = props.trail ?? '';
+    }
+    /** The `--on-word-*` time variables driven by this decoration's effective time. Falls back to `ctx.wordTime` when no `customTime` is set. */
+    getCssVariables(currentTime, ctx) {
+        const segStart = ctx.segTime.start;
+        const segEnd = ctx.segTime.end;
+        const effective = this.customTime ?? ctx.wordTime;
+        const start = effective.start;
+        const end = effective.end;
+        return {
+            [CssVariable.WORD_NOT_NARRATED_YET_STARTS]: `${(segStart - currentTime).toFixed(3)}s`,
+            [CssVariable.WORD_NOT_NARRATED_YET_ENDS]: `${(start - currentTime).toFixed(3)}s`,
+            [CssVariable.WORD_NOT_NARRATED_YET_DURATION]: `${(start - segStart).toFixed(3)}s`,
+            [CssVariable.WORD_BEING_NARRATED_STARTS]: `${(start - currentTime).toFixed(3)}s`,
+            [CssVariable.WORD_BEING_NARRATED_ENDS]: `${(end - currentTime).toFixed(3)}s`,
+            [CssVariable.WORD_BEING_NARRATED_DURATION]: `${(end - start).toFixed(3)}s`,
+            [CssVariable.WORD_ALREADY_NARRATED_STARTS]: `${(end - currentTime).toFixed(3)}s`,
+            [CssVariable.WORD_ALREADY_NARRATED_ENDS]: `${(segEnd - currentTime).toFixed(3)}s`,
+            [CssVariable.WORD_ALREADY_NARRATED_DURATION]: `${(segEnd - end).toFixed(3)}s`,
+        };
+    }
+    with(changes) {
+        return new Decoration({
+            id: this.id,
+            glyph: this.glyph,
+            customTime: this.customTime,
+            trail: this.trail,
+            ...changes,
+        });
+    }
+}
+//# sourceMappingURL=Decoration.js.map

package/dist/modules/document/Decoration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decoration.js","sourceRoot":"","sources":["../../../src/modules/document/Decoration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAwB5D;;;;;;;;GAQG;AACH,MAAM,OAAO,UAAU;IACrB,MAAM,CAAU,SAAS,GAAG,iBAAiB,CAAC;IAErC,EAAE,CAAS;IACX,KAAK,CAAS;IACd,UAAU,CAAsB;IAChC,KAAK,CAAS;IAEvB,YAAY,KAAsB;QAChC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC;QAC3C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;IACjC,CAAC;IAED,6IAA6I;IAC7I,eAAe,CAAC,WAAmB,EAAE,GAA4B;QAC/D,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC;QACnC,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC;QAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC,QAAQ,CAAC;QAClD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;QAC9B,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC;QAC1B,OAAO;YACL,CAAC,WAAW,CAAC,4BAA4B,CAAC,EAAE,GAAG,CAAC,QAAQ,GAAG,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YACrF,CAAC,WAAW,CAAC,0BAA0B,CAAC,EAAE,GAAG,CAAC,KAAK,GAAG,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YAChF,CAAC,WAAW,CAAC,8BAA8B,CAAC,EAAE,GAAG,CAAC,KAAK,GAAG,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YAEjF,CAAC,WAAW,CAAC,0BAA0B,CAAC,EAAE,GAAG,CAAC,KAAK,GAAG,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YAChF,CAAC,WAAW,CAAC,wBAAwB,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YAC5E,CAAC,WAAW,CAAC,4BAA4B,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YAE1E,CAAC,WAAW,CAAC,4BAA4B,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YAChF,CAAC,WAAW,CAAC,0BAA0B,CAAC,EAAE,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YACjF,CAAC,WAAW,CAAC,8BAA8B,CAAC,EAAE,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;SAC9E,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,OAAiC;QACpC,OAAO,IAAI,UAAU,CAAC;YACpB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC"}

package/dist/modules/document/Document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Document.d.ts","sourceRoot":"","sources":["../../../src/modules/document/Document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CACpD;AAED,qBAAa,QAAQ,CAAC,CAAC,GAAG,OAAO;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;gBAE1B,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC;IASnC,WAAW,IAAI,OAAO,EAAE;IAIxB,QAAQ,IAAI,IAAI,EAAE;IAIlB,QAAQ,IAAI,IAAI,EAAE;IAIlB,OAAO,IAAI,MAAM;IAIjB,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IASrD;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAO3D,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAIzC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE;IAiBjD,8DAA8D;IAC9D,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE;CAKlD"}
+{"version":3,"file":"Document.d.ts","sourceRoot":"","sources":["../../../src/modules/document/Document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CACpD;AAED,qBAAa,QAAQ,CAAC,CAAC,GAAG,OAAO;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;gBAE1B,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC;IAMnC,WAAW,IAAI,OAAO,EAAE;IAIxB,QAAQ,IAAI,IAAI,EAAE;IAIlB,QAAQ,IAAI,IAAI,EAAE;IAIlB,OAAO,IAAI,MAAM;IAIjB,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IASrD;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAO3D,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;IAIzC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE;IAiBjD,8DAA8D;IAC9D,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE;CAKlD"}