@soulcraft/sdk 1.0.0 → 1.1.0

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"}

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/kits/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module kits
+ * @description Factory for sdk.kits.* — the Soulcraft kit registry module.
+ *
+ * Provides read-only access to kit configurations from the `@soulcraft/kits`
+ * package. The package is an optional peer dependency loaded lazily via
+ * `createRequire` so that the SDK compiles and runs without it installed;
+ * calls gracefully return `null` / empty array when it is absent.
+ *
+ * The factory accepts an optional `bundledRegistry` override (used in tests)
+ * to inject a mock registry without needing the real package.
+ *
+ * @example
+ * ```typescript
+ * import { createKitsModule } from '@soulcraft/sdk/server'
+ *
+ * const kits = createKitsModule()
+ * const kit = await kits.load('wicks-and-whiskers')
+ * console.log(kit?.name) // "Wicks & Whiskers"
+ * ```
+ */
+import type { KitsModule, CreateKitsModuleOptions } from './types.js';
+/**
+ * Create the `sdk.kits.*` module.
+ *
+ * @param options - Optional overrides, primarily for testing.
+ * @returns A `KitsModule` backed by the `@soulcraft/kits` registry.
+ *
+ * @example
+ * ```typescript
+ * // In production:
+ * const kits = createKitsModule()
+ *
+ * // In tests — inject a mock registry to avoid the peer dep:
+ * const kits = createKitsModule({
+ *   bundledRegistry: { 'test-kit': { id: 'test-kit', name: 'Test Kit', ... } }
+ * })
+ * ```
+ */
+export declare function createKitsModule(options?: CreateKitsModuleOptions): KitsModule;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/kits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAsB,UAAU,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AA8BzF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,UAAU,CAkBlF"}

package/dist/modules/kits/index.js

@@ -0,0 +1,85 @@
+/**
+ * @module kits
+ * @description Factory for sdk.kits.* — the Soulcraft kit registry module.
+ *
+ * Provides read-only access to kit configurations from the `@soulcraft/kits`
+ * package. The package is an optional peer dependency loaded lazily via
+ * `createRequire` so that the SDK compiles and runs without it installed;
+ * calls gracefully return `null` / empty array when it is absent.
+ *
+ * The factory accepts an optional `bundledRegistry` override (used in tests)
+ * to inject a mock registry without needing the real package.
+ *
+ * @example
+ * ```typescript
+ * import { createKitsModule } from '@soulcraft/sdk/server'
+ *
+ * const kits = createKitsModule()
+ * const kit = await kits.load('wicks-and-whiskers')
+ * console.log(kit?.name) // "Wicks & Whiskers"
+ * ```
+ */
+import { createRequire } from 'node:module';
+// createRequire enables CJS-style require() inside an ESM module — the only
+// reliable way to conditionally load optional peer dependencies in Node/Bun ESM.
+const _require = createRequire(import.meta.url);
+// Module-level cache — loaded once per process, not per SDK instance.
+let _registryCache = undefined;
+/**
+ * Load the kit registry from the installed `@soulcraft/kits` package.
+ * Returns `null` when the package is not installed, allowing callers to
+ * degrade gracefully rather than throwing.
+ */
+function _getBundledRegistry() {
+    if (_registryCache !== undefined)
+        return _registryCache;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const kits = _require('@soulcraft/kits');
+        _registryCache = kits.kitRegistry ?? null;
+    }
+    catch {
+        _registryCache = null;
+    }
+    return _registryCache;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create the `sdk.kits.*` module.
+ *
+ * @param options - Optional overrides, primarily for testing.
+ * @returns A `KitsModule` backed by the `@soulcraft/kits` registry.
+ *
+ * @example
+ * ```typescript
+ * // In production:
+ * const kits = createKitsModule()
+ *
+ * // In tests — inject a mock registry to avoid the peer dep:
+ * const kits = createKitsModule({
+ *   bundledRegistry: { 'test-kit': { id: 'test-kit', name: 'Test Kit', ... } }
+ * })
+ * ```
+ */
+export function createKitsModule(options = {}) {
+    const getRegistry = options.bundledRegistry !== undefined
+        ? () => options.bundledRegistry ?? null
+        : _getBundledRegistry;
+    return {
+        async load(kitId) {
+            const registry = getRegistry();
+            if (!registry)
+                return null;
+            return registry[kitId] ?? null;
+        },
+        async list() {
+            const registry = getRegistry();
+            if (!registry)
+                return [];
+            return Object.values(registry);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/kits/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG3C,4EAA4E;AAC5E,iFAAiF;AACjF,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAE/C,sEAAsE;AACtE,IAAI,cAAc,GAA0D,SAAS,CAAA;AAErF;;;;GAIG;AACH,SAAS,mBAAmB;IAC1B,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,cAAc,CAAA;IACvD,IAAI,CAAC;QACH,8DAA8D;QAC9D,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAQ,CAAA;QAC/C,cAAc,GAAI,IAAI,CAAC,WAAkD,IAAI,IAAI,CAAA;IACnF,CAAC;IAAC,MAAM,CAAC;QACP,cAAc,GAAG,IAAI,CAAA;IACvB,CAAC;IACD,OAAO,cAAc,CAAA;AACvB,CAAC;AAED,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAmC,EAAE;IACpE,MAAM,WAAW,GAAG,OAAO,CAAC,eAAe,KAAK,SAAS;QACvD,CAAC,CAAC,GAA8C,EAAE,CAAC,OAAO,CAAC,eAAe,IAAI,IAAI;QAClF,CAAC,CAAC,mBAAmB,CAAA;IAEvB,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,KAAa;YACtB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;YAC9B,IAAI,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAA;YAC1B,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAA;QAChC,CAAC;QAED,KAAK,CAAC,IAAI;YACR,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;YAC9B,IAAI,CAAC,QAAQ;gBAAE,OAAO,EAAE,CAAA;YACxB,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QAChC,CAAC;KACF,CAAA;AACH,CAAC"}