@soulcraft/sdk 1.0.0 → 1.2.0

package/dist/modules/billing/usage-buffer.js

@@ -0,0 +1,141 @@
+/**
+ * @module billing/usage-buffer
+ * @description Fire-and-forget write-behind buffer for AI usage tracking.
+ *
+ * The usage buffer accumulates per-user token increments in memory and flushes
+ * them to the billing provider in a single batch write every 5 seconds. This
+ * pattern eliminates billing writes from the critical path of AI responses —
+ * the SSE `done` event is emitted before any billing I/O.
+ *
+ * Up to 5 seconds of usage may be lost on unclean process exits. This is
+ * acceptable for the billing use case — users are not double-charged on restart,
+ * and a few messages of under-counting per process lifetime is tolerable.
+ *
+ * @example
+ * ```typescript
+ * const buffer = new UsageBuffer(billingProvider)
+ *
+ * // Fire-and-forget — never await this:
+ * buffer.increment('user-123', 500, 200, 'claude-haiku-4-5-20251001', false)
+ *
+ * // On graceful shutdown:
+ * await buffer.flush()
+ * buffer.stop()
+ * ```
+ */
+/** Flush interval in milliseconds. */
+const FLUSH_INTERVAL_MS = 5_000;
+/**
+ * Write-behind usage buffer.
+ *
+ * Thread-safe within a single Node.js/Bun process (single-threaded event loop).
+ * Accumulates increments in memory and flushes to the billing provider on a
+ * 5-second interval. Also exposes `flush()` for explicit drain on shutdown.
+ */
+export class UsageBuffer {
+    provider;
+    pending = new Map();
+    _timer;
+    /**
+     * @param provider - The billing provider to flush to.
+     */
+    constructor(provider) {
+        this.provider = provider;
+        this._start();
+    }
+    /**
+     * Record a usage increment for a user.
+     *
+     * This method is synchronous and never throws. Usage is accumulated in memory
+     * and written to the billing backend on the next flush.
+     *
+     * @param userId - The authenticated user's ID.
+     * @param inputTokens - Input tokens consumed.
+     * @param outputTokens - Output tokens consumed.
+     * @param model - Model ID (e.g. `'claude-haiku-4-5-20251001'`).
+     * @param useTopUp - Whether this message drew from the top-up balance.
+     */
+    increment(userId, inputTokens, outputTokens, model, useTopUp) {
+        let acc = this.pending.get(userId);
+        if (!acc) {
+            acc = { messageCount: 0, inputTokens: 0, outputTokens: 0, topUpUsed: 0, byModel: {} };
+            this.pending.set(userId, acc);
+        }
+        acc.messageCount += 1;
+        acc.inputTokens += inputTokens;
+        acc.outputTokens += outputTokens;
+        if (useTopUp)
+            acc.topUpUsed += 1;
+        const existing = acc.byModel[model] ?? { input: 0, output: 0 };
+        acc.byModel[model] = {
+            input: existing.input + inputTokens,
+            output: existing.output + outputTokens,
+        };
+    }
+    /**
+     * Flush all pending usage increments to the billing provider.
+     *
+     * Called automatically on the 5-second interval, and on explicit calls from
+     * the billing module's `flush()` method (e.g. graceful shutdown).
+     *
+     * Errors are caught and logged — a flush failure never propagates to callers.
+     */
+    async flush() {
+        if (this.pending.size === 0)
+            return;
+        const snapshot = new Map(this.pending);
+        this.pending.clear();
+        const promises = [];
+        for (const [userId, acc] of snapshot) {
+            const batch = {
+                messageCount: acc.messageCount,
+                inputTokens: acc.inputTokens,
+                outputTokens: acc.outputTokens,
+                topUpUsed: acc.topUpUsed,
+                byModel: acc.byModel,
+            };
+            promises.push(this.provider.batchIncrementUsage(userId, batch).catch((err) => {
+                console.error(`[SDK/billing] Usage flush failed for user ${userId}:`, err);
+                // Re-enqueue the failed batch so it is retried on the next flush.
+                this._requeue(userId, acc);
+            }));
+        }
+        await Promise.allSettled(promises);
+    }
+    /**
+     * Stop the background flush interval.
+     * Call this during graceful shutdown after flushing.
+     */
+    stop() {
+        if (this._timer) {
+            clearInterval(this._timer);
+            this._timer = undefined;
+        }
+    }
+    // ── Private ──────────────────────────────────────────────────────────────
+    _start() {
+        this._timer = setInterval(() => {
+            void this.flush();
+        }, FLUSH_INTERVAL_MS);
+        // Allow the process to exit normally even if the interval is running.
+        if (this._timer.unref)
+            this._timer.unref();
+    }
+    _requeue(userId, acc) {
+        const existing = this.pending.get(userId);
+        if (!existing) {
+            this.pending.set(userId, acc);
+            return;
+        }
+        // Merge the failed batch back into any new accumulation.
+        existing.messageCount += acc.messageCount;
+        existing.inputTokens += acc.inputTokens;
+        existing.outputTokens += acc.outputTokens;
+        existing.topUpUsed += acc.topUpUsed;
+        for (const [model, counts] of Object.entries(acc.byModel)) {
+            const cur = existing.byModel[model] ?? { input: 0, output: 0 };
+            existing.byModel[model] = { input: cur.input + counts.input, output: cur.output + counts.output };
+        }
+    }
+}
+//# sourceMappingURL=usage-buffer.js.map

package/dist/modules/billing/usage-buffer.js.map

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

package/dist/modules/formats/types.d.ts

@@ -1,7 +1,69 @@
 /**
  * @module formats/types
- * @description Type definitions for sdk.formats.*
- * Implementation: Phase 4 per ADR-001.
+ * @description Soulcraft portable content format type definitions.
+ *
+ * This module exports the four core document formats used across the Soulcraft
+ * platform. All formats are pure data — JSON documents stored in the VFS and
+ * passed between products, AI tools, and rendering components.
+ *
+ * | Format  | Extension        | Purpose                                      |
+ * |---------|------------------|----------------------------------------------|
+ * | WVIZ    | `.wviz.json`     | Knowledge graph visualizations               |
+ * | WDOC    | `.wdoc`          | Rich text documents (TipTap/ProseMirror)     |
+ * | WSLIDE  | `.wslide.json`   | Slide deck presentations                     |
+ * | WQUIZ   | `.wquiz.json`    | Assessments and quizzes                      |
+ *
+ * Formats contain no runtime behavior — they are schema contracts. Products
+ * read them from the VFS, parse with `JSON.parse()`, and cast to the appropriate
+ * interface. The `SoulcraftFormat` discriminant on each document's `format` field
+ * enables safe narrowing at runtime.
+ *
+ * @example
+ * ```typescript
+ * import type { WdocDocument, WvizDocument, SoulcraftFormatDocument } from '@soulcraft/sdk'
+ *
+ * // Read from VFS and narrow to the correct type
+ * const buf = await sdk.vfs.readFile('/projects/notes.wdoc')
+ * const doc = JSON.parse(buf.toString('utf-8')) as SoulcraftFormatDocument
+ * if (doc.format === 'wdoc') {
+ *   const wdoc = doc as WdocDocument
+ *   console.log(wdoc.meta.title)
+ * }
+ * ```
  */
-export type {};
+export type { WvizDocument, WvizEntity, WvizEdge, WvizSnapshot, WvizViewType, } from './wviz.js';
+export type { WdocDocument, WdocMeta, WdocBlock, WdocInlineContent, WdocTextNode, WdocMark, WdocParagraphBlock, WdocHeadingBlock, WdocBlockquoteBlock, WdocCodeBlock, WdocBulletListBlock, WdocOrderedListBlock, WdocListItemBlock, WdocTaskListBlock, WdocTaskItemBlock, WdocImageBlock, WdocVideoBlock, WdocIconBlock, WdocSvgEmbedBlock, WdocEmbedBlock, WdocTableBlock, WdocTableRowBlock, WdocTableCellBlock, WdocTableHeaderBlock, WdocHorizontalRuleBlock, WdocCalloutBlock, } from './wdoc.js';
+export type { WslideDocument, WslideSlide, WslideBackground, WslideLayout, WslideTransition, WslideConfig, } from './wslide.js';
+export type { WquizDocument, WquizQuestion, WquizQuestionType, WquizAnswer, WquizScoringRules, } from './wquiz.js';
+/**
+ * Discriminant string identifying the Soulcraft document format.
+ *
+ * Stored as the `format` field on every document. Use this for narrowing:
+ * ```typescript
+ * if (doc.format === 'wdoc') { ... }
+ * ```
+ */
+export type SoulcraftFormat = 'wviz' | 'wdoc' | 'wslide' | 'wquiz';
+/**
+ * All Soulcraft format strings as a const array — useful for validation.
+ *
+ * @example
+ * ```typescript
+ * const isKnownFormat = (s: string): s is SoulcraftFormat =>
+ *   (SOULCRAFT_FORMATS as readonly string[]).includes(s)
+ * ```
+ */
+export declare const SOULCRAFT_FORMATS: readonly ["wviz", "wdoc", "wslide", "wquiz"];
+/**
+ * Minimal base shape shared by all Soulcraft format documents.
+ *
+ * Every Soulcraft document has a `format` discriminant and a `version` string.
+ * Cast an unknown JSON object to this type first, then narrow by `format`.
+ */
+export interface SoulcraftFormatDocument {
+    /** Format discriminant. Use to narrow to the specific document type. */
+    format: SoulcraftFormat;
+    /** Schema version string (e.g. `'1.0'`). */
+    version: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/modules/formats/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/formats/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,YAAY,EAAE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/formats/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,YAAY,EACV,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,aAAa,CAAA;AAEpB,YAAY,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAMnB;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,8CAAoF,CAAA;AAElH;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,MAAM,EAAE,eAAe,CAAA;IACvB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAA;CAChB"}

package/dist/modules/formats/types.js

@@ -1,7 +1,44 @@
 /**
  * @module formats/types
- * @description Type definitions for sdk.formats.*
- * Implementation: Phase 4 per ADR-001.
+ * @description Soulcraft portable content format type definitions.
+ *
+ * This module exports the four core document formats used across the Soulcraft
+ * platform. All formats are pure data — JSON documents stored in the VFS and
+ * passed between products, AI tools, and rendering components.
+ *
+ * | Format  | Extension        | Purpose                                      |
+ * |---------|------------------|----------------------------------------------|
+ * | WVIZ    | `.wviz.json`     | Knowledge graph visualizations               |
+ * | WDOC    | `.wdoc`          | Rich text documents (TipTap/ProseMirror)     |
+ * | WSLIDE  | `.wslide.json`   | Slide deck presentations                     |
+ * | WQUIZ   | `.wquiz.json`    | Assessments and quizzes                      |
+ *
+ * Formats contain no runtime behavior — they are schema contracts. Products
+ * read them from the VFS, parse with `JSON.parse()`, and cast to the appropriate
+ * interface. The `SoulcraftFormat` discriminant on each document's `format` field
+ * enables safe narrowing at runtime.
+ *
+ * @example
+ * ```typescript
+ * import type { WdocDocument, WvizDocument, SoulcraftFormatDocument } from '@soulcraft/sdk'
+ *
+ * // Read from VFS and narrow to the correct type
+ * const buf = await sdk.vfs.readFile('/projects/notes.wdoc')
+ * const doc = JSON.parse(buf.toString('utf-8')) as SoulcraftFormatDocument
+ * if (doc.format === 'wdoc') {
+ *   const wdoc = doc as WdocDocument
+ *   console.log(wdoc.meta.title)
+ * }
+ * ```
  */
-export {};
+/**
+ * All Soulcraft format strings as a const array — useful for validation.
+ *
+ * @example
+ * ```typescript
+ * const isKnownFormat = (s: string): s is SoulcraftFormat =>
+ *   (SOULCRAFT_FORMATS as readonly string[]).includes(s)
+ * ```
+ */
+export const SOULCRAFT_FORMATS = ['wviz', 'wdoc', 'wslide', 'wquiz'];
 //# sourceMappingURL=types.js.map

package/dist/modules/formats/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/formats/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/formats/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAsEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAA+C,CAAA"}

package/dist/modules/formats/wdoc.d.ts

@@ -0,0 +1,263 @@
+/**
+ * @module formats/wdoc
+ * @description Type definitions for the WDOC (Workshop Document) format.
+ *
+ * WDOC is a block-based JSON document format compatible with the TipTap/ProseMirror
+ * document schema. It extends plain Markdown with rich content blocks (video, icon,
+ * table, callout, embed) and is the native format for Workshop's document editor.
+ *
+ * WDOC files are stored in the VFS with the `.wdoc` extension. The format is a
+ * strict superset of Markdown — all Markdown content can be represented as WDOC,
+ * but not vice versa.
+ *
+ * @example Reading a WDOC from the VFS
+ * ```typescript
+ * const buf = await sdk.vfs.readFile('/projects/my-project/README.wdoc')
+ * const doc: WdocDocument = JSON.parse(buf.toString('utf-8'))
+ * console.log(doc.meta.title)
+ * ```
+ */
+/**
+ * A WDOC document — the top-level container for all block content.
+ */
+export interface WdocDocument {
+    /** Format discriminator. Always `'doc'`. */
+    type: 'doc';
+    /** Schema version. Currently `'1.0'`. */
+    version: string;
+    /** Document metadata (title, author, timestamps, tags). */
+    meta: WdocMeta;
+    /** Ordered list of content blocks. */
+    content: WdocBlock[];
+}
+/**
+ * Document-level metadata stored in the WDOC header.
+ */
+export interface WdocMeta {
+    /** Human-readable document title. */
+    title?: string;
+    /** Template ID this document was created from. */
+    template?: string;
+    /** ISO 8601 creation timestamp. */
+    created?: string;
+    /** ISO 8601 last-modified timestamp. */
+    modified?: string;
+    /** Document author (user ID or display name). */
+    author?: string;
+    /** Arbitrary tags for categorization. */
+    tags?: string[];
+    /** Whether this document was assembled from multiple source files. */
+    merged?: boolean;
+    /** Number of source files when `merged` is true. */
+    sourceCount?: number;
+}
+/**
+ * A text leaf node with optional formatting marks.
+ */
+export interface WdocTextNode {
+    type: 'text';
+    /** The raw text content. */
+    text: string;
+    /** Applied inline formatting marks. */
+    marks?: WdocMark[];
+}
+/**
+ * An inline formatting mark applied to a text node.
+ */
+export type WdocMark = {
+    type: 'bold';
+} | {
+    type: 'italic';
+} | {
+    type: 'strike';
+} | {
+    type: 'code';
+} | {
+    type: 'underline';
+} | {
+    type: 'link';
+    attrs: {
+        href: string;
+        target?: string;
+    };
+} | {
+    type: 'highlight';
+    attrs?: {
+        color?: string;
+    };
+} | {
+    type: 'textStyle';
+    attrs?: {
+        color?: string;
+        fontSize?: string;
+    };
+};
+/** Inline content — text nodes or inline icon blocks. */
+export type WdocInlineContent = WdocTextNode | WdocIconBlock;
+/**
+ * Union of all block types that can appear in a WDOC document.
+ */
+export type WdocBlock = WdocParagraphBlock | WdocHeadingBlock | WdocBlockquoteBlock | WdocCodeBlock | WdocBulletListBlock | WdocOrderedListBlock | WdocListItemBlock | WdocTaskListBlock | WdocTaskItemBlock | WdocImageBlock | WdocVideoBlock | WdocIconBlock | WdocSvgEmbedBlock | WdocEmbedBlock | WdocTableBlock | WdocTableRowBlock | WdocTableCellBlock | WdocTableHeaderBlock | WdocHorizontalRuleBlock | WdocCalloutBlock;
+/** A paragraph block. */
+export interface WdocParagraphBlock {
+    type: 'paragraph';
+    attrs?: {
+        textAlign?: 'left' | 'center' | 'right' | 'justify';
+    };
+    content?: WdocInlineContent[];
+}
+/** A heading block (H1–H6). */
+export interface WdocHeadingBlock {
+    type: 'heading';
+    attrs: {
+        level: 1 | 2 | 3 | 4 | 5 | 6;
+        textAlign?: 'left' | 'center' | 'right';
+    };
+    content?: WdocInlineContent[];
+}
+/** A block quotation. */
+export interface WdocBlockquoteBlock {
+    type: 'blockquote';
+    content?: WdocBlock[];
+}
+/** A fenced code block with optional language syntax highlighting. */
+export interface WdocCodeBlock {
+    type: 'codeBlock';
+    attrs?: {
+        language?: string;
+    };
+    content?: WdocTextNode[];
+}
+/** An unordered (bullet) list. */
+export interface WdocBulletListBlock {
+    type: 'bulletList';
+    content?: WdocListItemBlock[];
+}
+/** An ordered (numbered) list. */
+export interface WdocOrderedListBlock {
+    type: 'orderedList';
+    attrs?: {
+        start?: number;
+    };
+    content?: WdocListItemBlock[];
+}
+/** A single list item (used in both bullet and ordered lists). */
+export interface WdocListItemBlock {
+    type: 'listItem';
+    content?: WdocBlock[];
+}
+/** A task/checklist. */
+export interface WdocTaskListBlock {
+    type: 'taskList';
+    content?: WdocTaskItemBlock[];
+}
+/** A single task item with a checked/unchecked state. */
+export interface WdocTaskItemBlock {
+    type: 'taskItem';
+    attrs: {
+        checked: boolean;
+    };
+    content?: WdocBlock[];
+}
+/** A horizontal rule divider. */
+export interface WdocHorizontalRuleBlock {
+    type: 'horizontalRule';
+}
+/** An image block. */
+export interface WdocImageBlock {
+    type: 'image';
+    attrs: {
+        src: string;
+        alt?: string;
+        title?: string;
+        width?: number;
+        height?: number;
+    };
+}
+/** A video block (self-hosted or embedded). */
+export interface WdocVideoBlock {
+    type: 'video';
+    attrs: {
+        src: string;
+        provider?: 'youtube' | 'vimeo' | 'self-hosted';
+        poster?: string;
+        title?: string;
+        width?: number;
+        height?: number;
+    };
+}
+/** An inline icon from the Iconify library. */
+export interface WdocIconBlock {
+    type: 'icon';
+    attrs: {
+        /** Iconify icon identifier, e.g. `'mdi:rocket-launch'`. */
+        icon: string;
+        size?: number;
+        color?: string;
+    };
+    marks?: WdocMark[];
+}
+/** An SVG file embed. */
+export interface WdocSvgEmbedBlock {
+    type: 'svgEmbed';
+    attrs: {
+        /** Path to the `.svg` file in the VFS. */
+        src: string;
+        editable?: boolean;
+        /** When true, inline the SVG content rather than referencing it. */
+        inline?: boolean;
+        width?: number;
+        height?: number;
+    };
+    /** Inlined SVG markup when `attrs.inline` is true. */
+    content?: string;
+}
+/** An oEmbed/iframe embed (Twitter, Figma, CodePen, etc.). */
+export interface WdocEmbedBlock {
+    type: 'embed';
+    attrs: {
+        url: string;
+        provider?: 'twitter' | 'figma' | 'codepen' | 'youtube' | 'gist' | 'other';
+        width?: number;
+        height?: number;
+    };
+}
+/** A table block. */
+export interface WdocTableBlock {
+    type: 'table';
+    content?: WdocTableRowBlock[];
+}
+/** A table row. */
+export interface WdocTableRowBlock {
+    type: 'tableRow';
+    content?: (WdocTableCellBlock | WdocTableHeaderBlock)[];
+}
+/** A table body cell. */
+export interface WdocTableCellBlock {
+    type: 'tableCell';
+    attrs?: {
+        colspan?: number;
+        rowspan?: number;
+    };
+    content?: WdocBlock[];
+}
+/** A table header cell. */
+export interface WdocTableHeaderBlock {
+    type: 'tableHeader';
+    attrs?: {
+        colspan?: number;
+        rowspan?: number;
+    };
+    content?: WdocBlock[];
+}
+/** A styled callout/alert block. */
+export interface WdocCalloutBlock {
+    type: 'callout';
+    attrs: {
+        variant: 'info' | 'warning' | 'success' | 'error' | 'tip';
+        /** Optional Iconify icon override. */
+        icon?: string;
+    };
+    content?: WdocBlock[];
+}
+//# sourceMappingURL=wdoc.d.ts.map

package/dist/modules/formats/wdoc.d.ts.map

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

package/dist/modules/formats/wdoc.js

@@ -0,0 +1,21 @@
+/**
+ * @module formats/wdoc
+ * @description Type definitions for the WDOC (Workshop Document) format.
+ *
+ * WDOC is a block-based JSON document format compatible with the TipTap/ProseMirror
+ * document schema. It extends plain Markdown with rich content blocks (video, icon,
+ * table, callout, embed) and is the native format for Workshop's document editor.
+ *
+ * WDOC files are stored in the VFS with the `.wdoc` extension. The format is a
+ * strict superset of Markdown — all Markdown content can be represented as WDOC,
+ * but not vice versa.
+ *
+ * @example Reading a WDOC from the VFS
+ * ```typescript
+ * const buf = await sdk.vfs.readFile('/projects/my-project/README.wdoc')
+ * const doc: WdocDocument = JSON.parse(buf.toString('utf-8'))
+ * console.log(doc.meta.title)
+ * ```
+ */
+export {};
+//# sourceMappingURL=wdoc.js.map

package/dist/modules/formats/wdoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wdoc.js","sourceRoot":"","sources":["../../../src/modules/formats/wdoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}