@soulcraft/sdk 1.0.0 → 1.2.0

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

@@ -0,0 +1,122 @@
+/**
+ * @module formats/wquiz
+ * @description Type definitions for the WQUIZ (Workshop Quiz) document format.
+ *
+ * WQUIZ documents are portable assessment and quiz definitions. They support
+ * multiple-choice, true/false, short-answer, and essay question types, with
+ * per-question point values, optional explanations, and configurable scoring.
+ *
+ * WQUIZ files are stored in the VFS with the `.wquiz.json` extension. Academy
+ * uses them for module assessments; Workshop can render them for self-check quizzes.
+ *
+ * Question content supports rich formatting via WDOC blocks, enabling code
+ * snippets, images, and callouts inside questions and answer choices.
+ *
+ * @example Reading a WQUIZ from the VFS
+ * ```typescript
+ * const buf = await sdk.vfs.readFile('/assessments/module-1.wquiz.json')
+ * const quiz: WquizDocument = JSON.parse(buf.toString('utf-8'))
+ * console.log(`${quiz.questions.length} questions, ${quiz.scoring.totalPoints} points`)
+ * ```
+ */
+import type { WdocBlock } from './wdoc.js';
+/**
+ * A WQUIZ assessment document.
+ */
+export interface WquizDocument {
+    /** Format discriminator. Always `'wquiz'`. */
+    format: 'wquiz';
+    /** Schema version. Currently `'1.0'`. */
+    version: '1.0';
+    /** Quiz title. */
+    title: string;
+    /** Optional description shown to the learner before starting. */
+    description?: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt?: string;
+    /** ISO 8601 last-modified timestamp. */
+    updatedAt?: string;
+    /** Ordered list of questions. */
+    questions: WquizQuestion[];
+    /** Scoring configuration. */
+    scoring: WquizScoringRules;
+    /** Optional metadata for product-specific use (e.g. Academy module ID). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Question type discriminant.
+ *
+ * - `multiple-choice` — One or more correct answers from a fixed list
+ * - `true-false` — Binary correct/incorrect assertion
+ * - `short-answer` — Free-text response, graded by exact match or AI review
+ * - `essay` — Long-form free-text response, graded by human or AI review
+ */
+export type WquizQuestionType = 'multiple-choice' | 'true-false' | 'short-answer' | 'essay';
+/**
+ * A single quiz question.
+ */
+export interface WquizQuestion {
+    /** Stable unique identifier for this question. */
+    id: string;
+    /** Question type. */
+    type: WquizQuestionType;
+    /** Plain-text question stem (used as fallback when `content` is absent). */
+    text: string;
+    /** Rich-text question content (WDOC blocks). When present, rendered instead of `text`. */
+    content?: WdocBlock[];
+    /** Available answer choices (for `multiple-choice` and `true-false` types). */
+    answers: WquizAnswer[];
+    /**
+     * IDs of correct answer choices.
+     * - For `multiple-choice`: one or more answer IDs.
+     * - For `true-false`: one of the two generated answer IDs.
+     * - For `short-answer`: the accepted text strings (exact match).
+     * - For `essay`: omit; graded externally.
+     */
+    correct?: string[];
+    /** Explanation shown after the learner answers (Markdown or plain text). */
+    explanation?: string;
+    /** Point value for this question. Defaults to `1`. */
+    points?: number;
+    /** Whether to randomize the order of `answers` when presenting. Defaults to `false`. */
+    shuffleAnswers?: boolean;
+}
+/**
+ * A single answer choice within a question.
+ */
+export interface WquizAnswer {
+    /** Stable unique identifier for this answer choice. */
+    id: string;
+    /** Plain-text answer label (used as fallback when `content` is absent). */
+    text: string;
+    /** Rich-text answer content (WDOC blocks). When present, rendered instead of `text`. */
+    content?: WdocBlock[];
+    /** Per-choice feedback shown after the learner answers. */
+    feedback?: string;
+    /**
+     * Partial-credit weight (0–1) for this answer choice.
+     * Only used when `WquizScoringRules.allowPartialCredit` is `true`.
+     * A weight of `1.0` means full credit; `0.5` means half credit.
+     */
+    weight?: number;
+}
+/**
+ * Scoring rules for the entire quiz.
+ */
+export interface WquizScoringRules {
+    /** Minimum score (as a percentage 0–100) required to pass. */
+    passingScore: number;
+    /** Total possible points across all questions. */
+    totalPoints: number;
+    /** Whether partial credit is allowed on multi-select questions. Defaults to `false`. */
+    allowPartialCredit?: boolean;
+    /** Whether to penalize wrong answers (negative marking). Defaults to `false`. */
+    negativeMark?: boolean;
+    /** Maximum number of attempts allowed. `0` = unlimited. Defaults to `0`. */
+    maxAttempts?: number;
+    /** Time limit in seconds. `0` = no limit. Defaults to `0`. */
+    timeLimitSeconds?: number;
+    /** Whether to randomize question order when presenting. Defaults to `false`. */
+    shuffleQuestions?: boolean;
+}
+//# sourceMappingURL=wquiz.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wquiz.d.ts","sourceRoot":"","sources":["../../../src/modules/formats/wquiz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAM1C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAA;IACf,yCAAyC;IACzC,OAAO,EAAE,KAAK,CAAA;IACd,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iCAAiC;IACjC,SAAS,EAAE,aAAa,EAAE,CAAA;IAC1B,6BAA6B;IAC7B,OAAO,EAAE,iBAAiB,CAAA;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAMD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,YAAY,GAAG,cAAc,GAAG,OAAO,CAAA;AAE3F;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAA;IACV,qBAAqB;IACrB,IAAI,EAAE,iBAAiB,CAAA;IACvB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;IACZ,0FAA0F;IAC1F,OAAO,CAAC,EAAE,SAAS,EAAE,CAAA;IACrB,+EAA+E;IAC/E,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wFAAwF;IACxF,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAA;IACV,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;IACZ,wFAAwF;IACxF,OAAO,CAAC,EAAE,SAAS,EAAE,CAAA;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAA;IACpB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAA;IACnB,wFAAwF;IACxF,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,iFAAiF;IACjF,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B"}

package/dist/modules/formats/wquiz.js

@@ -0,0 +1,23 @@
+/**
+ * @module formats/wquiz
+ * @description Type definitions for the WQUIZ (Workshop Quiz) document format.
+ *
+ * WQUIZ documents are portable assessment and quiz definitions. They support
+ * multiple-choice, true/false, short-answer, and essay question types, with
+ * per-question point values, optional explanations, and configurable scoring.
+ *
+ * WQUIZ files are stored in the VFS with the `.wquiz.json` extension. Academy
+ * uses them for module assessments; Workshop can render them for self-check quizzes.
+ *
+ * Question content supports rich formatting via WDOC blocks, enabling code
+ * snippets, images, and callouts inside questions and answer choices.
+ *
+ * @example Reading a WQUIZ from the VFS
+ * ```typescript
+ * const buf = await sdk.vfs.readFile('/assessments/module-1.wquiz.json')
+ * const quiz: WquizDocument = JSON.parse(buf.toString('utf-8'))
+ * console.log(`${quiz.questions.length} questions, ${quiz.scoring.totalPoints} points`)
+ * ```
+ */
+export {};
+//# sourceMappingURL=wquiz.js.map

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

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

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

@@ -0,0 +1,130 @@
+/**
+ * @module formats/wslide
+ * @description Type definitions for the WSLIDE (Workshop Slide Deck) document format.
+ *
+ * WSLIDE documents are portable slide presentations. Each slide contains rich
+ * content blocks (in WDOC format), a layout preset, optional background, and
+ * transition configuration.
+ *
+ * WSLIDE files are stored in the VFS with the `.wslide.json` extension and can
+ * be rendered by any Soulcraft product that embeds the Workshop slideshow viewer.
+ *
+ * Content blocks within each slide reuse the WDOC block types — the same block
+ * system that powers the Workshop document editor applies inside slides.
+ *
+ * @example Reading a WSLIDE document from the VFS
+ * ```typescript
+ * const buf = await sdk.vfs.readFile('/presentations/onboarding.wslide.json')
+ * const deck: WslideDocument = JSON.parse(buf.toString('utf-8'))
+ * console.log(`${deck.slides.length} slides`)
+ * ```
+ */
+import type { WdocBlock } from './wdoc.js';
+/**
+ * Predefined layout preset for a slide.
+ *
+ * - `title` — Centered title + subtitle
+ * - `content` — Title bar + full content area below
+ * - `two-column` — Title bar + two equal-width content columns
+ * - `image-left` — Image panel on the left, content on the right
+ * - `image-right` — Content on the left, image panel on the right
+ * - `image-full` — Full-bleed background image with overlaid text
+ * - `blank` — No preset layout; positions are fully custom
+ */
+export type WslideLayout = 'title' | 'content' | 'two-column' | 'image-left' | 'image-right' | 'image-full' | 'blank';
+/**
+ * Slide-to-slide transition animation.
+ *
+ * - `none` — Instant cut
+ * - `fade` — Cross-fade dissolve
+ * - `slide` / `slide-left` — Slide the new content in from the right
+ * - `slide-right` — Slide the new content in from the left
+ * - `slide-up` / `slide-down` — Vertical slide
+ * - `zoom` / `zoom-in` — Zoom in from center
+ * - `zoom-out` — Zoom out to reveal next slide
+ */
+export type WslideTransition = 'none' | 'fade' | 'slide' | 'slide-left' | 'slide-right' | 'slide-up' | 'slide-down' | 'zoom' | 'zoom-in' | 'zoom-out';
+/**
+ * A WSLIDE presentation document.
+ */
+export interface WslideDocument {
+    /** Format discriminator. Always `'wslide'`. */
+    format: 'wslide';
+    /** Schema version. Currently `'1.0'`. */
+    version: '1.0';
+    /** Presentation title. */
+    title?: string;
+    /** Author name or user ID. */
+    author?: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt?: string;
+    /** ISO 8601 last-modified timestamp. */
+    updatedAt?: string;
+    /** Ordered list of slides. */
+    slides: WslideSlide[];
+    /** Presentation-level display settings. */
+    config?: WslideConfig;
+}
+/**
+ * A single slide in a WSLIDE presentation.
+ */
+export interface WslideSlide {
+    /** Unique slide identifier (stable across reorders). */
+    id: string;
+    /** Slide title shown in the navigation/outline panel. */
+    title: string;
+    /** Rich content blocks (WDOC format). */
+    content: WdocBlock[];
+    /** Speaker notes (plain text or Markdown). Not shown to the audience. */
+    notes?: string;
+    /** Background override for this slide (overrides the presentation default). */
+    background?: WslideBackground;
+    /** Layout preset for this slide. */
+    layout?: WslideLayout;
+    /** Transition to use when advancing TO this slide. */
+    transition?: WslideTransition;
+    /** Arbitrary per-slide metadata for product-specific use. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Slide background configuration.
+ */
+export interface WslideBackground {
+    /** Background type. */
+    type: 'color' | 'gradient' | 'image';
+    /**
+     * Background value:
+     * - `color`: CSS hex or named color, e.g. `'#1a1a2e'`
+     * - `gradient`: CSS gradient string, e.g. `'linear-gradient(135deg, #1a1a2e, #16213e)'`
+     * - `image`: URL or VFS path to an image file
+     */
+    value: string;
+    /** Opacity for image backgrounds (0–1). Defaults to 1. */
+    opacity?: number;
+}
+/**
+ * Presentation-level display configuration.
+ */
+export interface WslideConfig {
+    /** Auto-advance interval in seconds. `0` = manual navigation. Defaults to `0`. */
+    autoAdvance?: number;
+    /** Show slide numbers in the viewer. Defaults to `true`. */
+    showSlideNumbers?: boolean;
+    /** Show a progress bar across the bottom. Defaults to `true`. */
+    showProgress?: boolean;
+    /** Show previous/next navigation arrows. Defaults to `true`. */
+    showNavigation?: boolean;
+    /** Show the speaker notes panel. Defaults to `false`. */
+    showNotes?: boolean;
+    /** Enable keyboard navigation (arrow keys, space). Defaults to `true`. */
+    keyboardNavigation?: boolean;
+    /** Loop back to the first slide after the last. Defaults to `false`. */
+    loop?: boolean;
+    /** Default transition for all slides (overridden per-slide by `WslideSlide.transition`). */
+    defaultTransition?: WslideTransition;
+    /** Slide aspect ratio. Defaults to `'16:9'`. */
+    aspectRatio?: '16:9' | '4:3' | '16:10' | 'auto';
+    /** Color theme. Defaults to `'auto'` (follows system preference). */
+    theme?: 'dark' | 'light' | 'auto';
+}
+//# sourceMappingURL=wslide.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wslide.d.ts","sourceRoot":"","sources":["../../../src/modules/formats/wslide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAM1C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,SAAS,GACT,YAAY,GACZ,YAAY,GACZ,aAAa,GACb,YAAY,GACZ,OAAO,CAAA;AAEX;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,MAAM,GACN,OAAO,GACP,YAAY,GACZ,aAAa,GACb,UAAU,GACV,YAAY,GACZ,MAAM,GACN,SAAS,GACT,UAAU,CAAA;AAMd;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,MAAM,EAAE,QAAQ,CAAA;IAChB,yCAAyC;IACzC,OAAO,EAAE,KAAK,CAAA;IACd,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8BAA8B;IAC9B,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAA;IACV,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb,yCAAyC;IACzC,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+EAA+E;IAC/E,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAC7B,oCAAoC;IACpC,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,sDAAsD;IACtD,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,CAAA;IACpC;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,wEAAwE;IACxE,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,4FAA4F;IAC5F,iBAAiB,CAAC,EAAE,gBAAgB,CAAA;IACpC,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAAA;IAC/C,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAA;CAClC"}

package/dist/modules/formats/wslide.js

@@ -0,0 +1,23 @@
+/**
+ * @module formats/wslide
+ * @description Type definitions for the WSLIDE (Workshop Slide Deck) document format.
+ *
+ * WSLIDE documents are portable slide presentations. Each slide contains rich
+ * content blocks (in WDOC format), a layout preset, optional background, and
+ * transition configuration.
+ *
+ * WSLIDE files are stored in the VFS with the `.wslide.json` extension and can
+ * be rendered by any Soulcraft product that embeds the Workshop slideshow viewer.
+ *
+ * Content blocks within each slide reuse the WDOC block types — the same block
+ * system that powers the Workshop document editor applies inside slides.
+ *
+ * @example Reading a WSLIDE document from the VFS
+ * ```typescript
+ * const buf = await sdk.vfs.readFile('/presentations/onboarding.wslide.json')
+ * const deck: WslideDocument = JSON.parse(buf.toString('utf-8'))
+ * console.log(`${deck.slides.length} slides`)
+ * ```
+ */
+export {};
+//# sourceMappingURL=wslide.js.map

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

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

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

@@ -0,0 +1,114 @@
+/**
+ * @module formats/wviz
+ * @description Type definitions for the WVIZ (Soulcraft Visualization) document format.
+ *
+ * WVIZ documents are portable, self-contained graph snapshots. They capture a
+ * filtered view of a Brainy knowledge graph — entities and edges — along with
+ * enough metadata to render them in any Soulcraft view (graph, mindmap, tree, etc.)
+ * without requiring a live Brainy connection.
+ *
+ * WVIZ files are stored in the VFS with the `.wviz.json` extension and can be
+ * exported from Workshop's Explore panel or generated programmatically.
+ *
+ * @example Reading a WVIZ document from the VFS
+ * ```typescript
+ * const buf = await sdk.vfs.readFile('/visualizations/product-graph.wviz.json')
+ * const viz: WvizDocument = JSON.parse(buf.toString('utf-8'))
+ * console.log(viz.entities.length) // number of nodes
+ * ```
+ */
+/**
+ * The rendering mode to use when displaying a WVIZ document.
+ *
+ * - `graph` — Force-directed node-link diagram (default)
+ * - `mindmap` — Radial tree rooted at a central concept
+ * - `tree` — Hierarchical top-down tree layout
+ * - `tapestry` — Narrative woven-thread visualization (Soulcraft-specific)
+ * - `workflow` — Left-to-right directed flow
+ * - `board` — Kanban-style column layout
+ * - `list` — Flat list view with metadata columns
+ * - `table` — Sortable tabular grid
+ * - `gallery` — Card grid with thumbnails
+ * - `calendar` — Date-based calendar view
+ * - `timeline` — Chronological timeline
+ */
+export type WvizViewType = 'graph' | 'mindmap' | 'tree' | 'tapestry' | 'workflow' | 'board' | 'list' | 'table' | 'gallery' | 'calendar' | 'timeline';
+/**
+ * A self-contained visualization document.
+ *
+ * Entities and edges are snapshotted at export time. They are NOT live references
+ * to a Brainy graph — rendering does not require a Brainy connection.
+ */
+export interface WvizDocument {
+    /** Format discriminator. Always `'wviz'`. */
+    format: 'wviz';
+    /** Schema version. Currently `'1.0'`. */
+    version: '1.0';
+    /** Human-readable document title. */
+    title?: string;
+    /** Which view type to render this document with. */
+    viewType: WvizViewType;
+    /**
+     * View-specific configuration (layout algorithm, color scheme, label settings, etc.).
+     * Shape is view-type-specific and interpreted by the rendering component.
+     */
+    viewConfig: Record<string, unknown>;
+    /** Snapshotted entity list. These are not live Brainy entity references. */
+    entities: WvizEntity[];
+    /** Edges connecting entities. */
+    edges: WvizEdge[];
+    /**
+     * Saved node positions for force-directed layouts.
+     * Key is entity ID; value is `{ x, y }` in canvas coordinates.
+     * When present, the layout is pinned rather than recalculated on each render.
+     */
+    positions?: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Provenance metadata describing where this snapshot came from.
+     * Recorded at export time; not updated when entities change in Brainy.
+     */
+    snapshot?: WvizSnapshot;
+}
+/**
+ * A single entity (node) in a WVIZ document.
+ */
+export interface WvizEntity {
+    /** Unique identifier within this document (matches the Brainy entity ID at export time). */
+    id: string;
+    /** Brainy NounType string (e.g. `'concept'`, `'person'`, `'task'`). */
+    type: string;
+    /** Human-readable name shown as the node label. */
+    name: string;
+    /** Additional metadata fields captured at export time. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A directed edge (relationship) between two entities in a WVIZ document.
+ */
+export interface WvizEdge {
+    /** Source entity ID. Must match a `WvizEntity.id` in the same document. */
+    from: string;
+    /** Target entity ID. Must match a `WvizEntity.id` in the same document. */
+    to: string;
+    /** Brainy VerbType string describing the relationship (e.g. `'relatesTo'`, `'blocks'`). */
+    verb: string;
+}
+/**
+ * Provenance metadata for a WVIZ snapshot.
+ */
+export interface WvizSnapshot {
+    /** ISO 8601 timestamp when this snapshot was taken. */
+    createdAt: string;
+    /** Workspace ID the entities were exported from. */
+    sourceWorkspace?: string;
+    /** Collection or workbench name at time of export. */
+    sourceWorkbench?: string;
+    /** Total entity count in the source (may differ from `entities.length` after filtering). */
+    entityCount: number;
+    /** Total edge count in the source. */
+    edgeCount: number;
+}
+//# sourceMappingURL=wviz.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wviz.d.ts","sourceRoot":"","sources":["../../../src/modules/formats/wviz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,UAAU,GACV,OAAO,GACP,MAAM,GACN,OAAO,GACP,SAAS,GACT,UAAU,GACV,UAAU,CAAA;AAMd;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAA;IACd,yCAAyC;IACzC,OAAO,EAAE,KAAK,CAAA;IACd,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,QAAQ,EAAE,YAAY,CAAA;IACtB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,4EAA4E;IAC5E,QAAQ,EAAE,UAAU,EAAE,CAAA;IACtB,iCAAiC;IACjC,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4FAA4F;IAC5F,EAAE,EAAE,MAAM,CAAA;IACV,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAA;IACV,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAA;CAClB"}

package/dist/modules/formats/wviz.js

@@ -0,0 +1,21 @@
+/**
+ * @module formats/wviz
+ * @description Type definitions for the WVIZ (Soulcraft Visualization) document format.
+ *
+ * WVIZ documents are portable, self-contained graph snapshots. They capture a
+ * filtered view of a Brainy knowledge graph — entities and edges — along with
+ * enough metadata to render them in any Soulcraft view (graph, mindmap, tree, etc.)
+ * without requiring a live Brainy connection.
+ *
+ * WVIZ files are stored in the VFS with the `.wviz.json` extension and can be
+ * exported from Workshop's Explore panel or generated programmatically.
+ *
+ * @example Reading a WVIZ document from the VFS
+ * ```typescript
+ * const buf = await sdk.vfs.readFile('/visualizations/product-graph.wviz.json')
+ * const viz: WvizDocument = JSON.parse(buf.toString('utf-8'))
+ * console.log(viz.entities.length) // number of nodes
+ * ```
+ */
+export {};
+//# sourceMappingURL=wviz.js.map

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

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

package/dist/modules/hall/browser.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @module modules/hall/browser
+ * @description Browser-side Hall room client — joins a WebRTC room via a session token.
+ *
+ * `joinHallRoom` is the browser entry point for Hall real-time communication.
+ * It opens a WebSocket to the Hall signaling endpoint, negotiates a WebRTC peer
+ * connection via offer/answer/ICE, and returns a `HallRoomHandle` with typed events
+ * for tracks, transcripts, concept mentions, and room lifecycle.
+ *
+ * **Auth model:** The browser never sees the product's shared secret. The product
+ * backend mints a short-lived HMAC session token (via `sdk.hall.createSessionToken`)
+ * and passes it to the browser. The browser passes the token to `joinHallRoom` — that
+ * is the only browser credential.
+ *
+ * This module has no server-only dependencies and is safe to bundle for the browser.
+ * It does require `RTCPeerConnection` and `WebSocket` to be available (standard in
+ * all modern browsers; not available in Node.js without polyfills).
+ *
+ * @example
+ * ```typescript
+ * import { joinHallRoom } from '@soulcraft/sdk/client'
+ *
+ * // 1. Get token from product backend:
+ * const { token, hallUrl } = await fetch('/api/session/join').then(r => r.json())
+ *
+ * // 2. Get camera + mic:
+ * const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })
+ *
+ * // 3. Join room:
+ * const room = await joinHallRoom({ token, hallUrl })
+ * room.addStream(stream)
+ *
+ * // 4. Handle events:
+ * room.on('trackAdded', ({ peerId, streams }) => {
+ *   document.getElementById(`video-${peerId}`).srcObject = streams[0]
+ * })
+ * room.on('transcript', ({ peerId, text, isFinal }) => {
+ *   if (isFinal) appendCaption(peerId, text)
+ * })
+ * room.on('conceptMention', ({ nodeId, confidence }) => pulseGraphNode(nodeId, confidence))
+ *
+ * // 5. On leave:
+ * room.close()
+ * ```
+ */
+import type { HallRoomHandle } from './types.js';
+/**
+ * Options for {@link joinHallRoom}.
+ */
+export interface JoinHallRoomOptions {
+    /**
+     * The session token issued by the product backend via `sdk.hall.createSessionToken()`.
+     * Embedded in the Hall WebSocket URL — never sent as a header or query param separately.
+     */
+    token: string;
+    /**
+     * The Hall server WebSocket base URL (e.g. `"wss://hall.soulcraft.com"`).
+     * Provided by the product backend alongside the token.
+     */
+    hallUrl: string;
+    /**
+     * Optional RTCConfiguration overrides (e.g. additional STUN/TURN servers).
+     * Hall's in-process TURN server is always included automatically via the signaling handshake.
+     * Pass additional servers here if you have a separate STUN/TURN setup.
+     */
+    iceServers?: RTCIceServer[];
+}
+/**
+ * Join a Hall room from the browser using a session token.
+ *
+ * Opens a WebSocket to `{hallUrl}/ws/session/{token}`, creates an `RTCPeerConnection`,
+ * performs the offer/answer/ICE exchange, and resolves once the peer connection reaches
+ * `connected` state. Returns a {@link HallRoomHandle} with typed events.
+ *
+ * @param options - Token, Hall URL, and optional ICE server overrides.
+ * @returns A connected `HallRoomHandle`.
+ * @throws {Error} If the signaling handshake fails or the connection times out.
+ *
+ * @example
+ * ```typescript
+ * const room = await joinHallRoom({ token, hallUrl: 'wss://hall.soulcraft.com' })
+ * room.addStream(localStream)
+ * room.on('trackAdded', ({ peerId, streams }) => renderVideo(peerId, streams[0]))
+ * room.on('transcript', ({ text, isFinal }) => { if (isFinal) showCaption(text) })
+ * ```
+ */
+export declare function joinHallRoom(options: JoinHallRoomOptions): Promise<HallRoomHandle>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/modules/hall/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/modules/hall/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EACV,cAAc,EAQf,MAAM,YAAY,CAAA;AAoBnB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,YAAY,EAAE,CAAA;CAC5B;AAgFD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgIxF"}