@lssm/example.learning-journey-duo-drills 0.0.0-canary-20251217080011 → 0.0.0-canary-20251217083314

package/dist/libs/contracts/dist/docs/tech/templates/runtime.docblock.js

@@ -0,0 +1,20 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/contracts/dist/docs/tech/templates/runtime.docblock.js
+const tech_templates_runtime_DocBlocks = [{
+	id: "docs.tech.templates.runtime",
+	title: "ContractSpec Template Runtime (Phase 9)",
+	summary: "Phase 9 introduces a full local-first runtime for templates so anyone can preview apps directly in the browser without provisioning any infrastructure.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/templates/runtime",
+	tags: [
+		"tech",
+		"templates",
+		"runtime"
+	],
+	body: "## ContractSpec Template Runtime (Phase 9)\n\nPhase 9 introduces a full local-first runtime for templates so anyone can preview apps directly in the browser without provisioning any infrastructure.\n\n### Building Blocks\n\n- **Local database** – `@lssm/lib.runtime-local` wraps `sql.js` (SQLite WASM) and `IndexedDB` so we can seed demo data, run migrations, and persist state between sessions. Tests point the runtime to `node_modules/sql.js/dist` so CI doesn’t need a browser.\n- **Local GraphQL** – `LocalGraphQLClient` wires Apollo Client + SchemaLink to resolvers for tasks, messaging, and i18n recipes. All `/templates`, `/studio`, and `/sandbox` previews use those resolvers so we never call remote APIs during demos.\n- **Template registry + installer** – `.../templates/registry.ts` stores the catalog (todos, messaging, recipes). `TemplateInstaller` can seed the runtime (`install`) or export a base64 snapshot via the new `saveTemplateToStudio` mutation.\n- **TemplateShell** – Shared UI wrapper that creates a `TemplateRuntimeProvider`, shows `LocalDataIndicator`, and (optionally) surfaces the new `SaveToStudioButton`.\n\n### Runtime Flows\n\n1. `/templates` now opens a modal that renders `TemplateShell` for each template. Users can explore without leaving the marketing site.\n2. `/studio` switches to a tabbed mini-app (Projects, Canvas, Specs, Deploy) to showcase Studio surfaces with mock data. Visitors see a **preview** shell, while authenticated users (Better Auth via Sigil) unlock full persistence, versioning, and deployment controls.\n3. `/sandbox` lets visitors pick a template and mode (Playground, Spec Editor, Visual Builder). The console at the bottom streams runtime events for transparency.\n\n### GraphQL Mutations\n\n- `saveTemplateToStudio(input: SaveTemplateInput!): SaveTemplateResult!` writes a placeholder project + spec so that templates installed from the sandbox appear in Studio. The mutation is intentionally simple right now: it records which template was imported, stores metadata, and returns `{ projectId, status: 'QUEUED' }` for the UI.\n- `saveCanvasDraft(input: SaveCanvasDraftInput!): CanvasVersion!` snapshots the current Visual Builder nodes to a draft version tied to a canvas overlay. Inputs include `canvasId`, arbitrary `nodes` JSON, and an optional `label`. The resolver enforces org/org access before calling `CanvasVersionManager`.\n- `deployCanvasVersion(input: DeployCanvasVersionInput!): CanvasVersion!` promotes a previously saved draft (`versionId`) to the deployed state. The returned object includes `status`, `nodes`, `createdAt`, and `createdBy` for UI timelines.\n- `undoCanvasVersion(input: UndoCanvasInput!): CanvasVersion` rewinds the visual builder to the prior snapshot (returns `null` when history is empty) so Studio’s toolbar can surface “Undo” without shelling out to local storage.\n\n### Studio GraphQL endpoint\n\n- The landing app exposes the Studio schema at `/api/studio/graphql` via Yoga so React Query hooks (`useStudioProjects`, `useCreateStudioProject`, `useDeployStudioProject`, etc.) can talk to the bundle without spinning up a separate server.\n\n### Spec Editor typing\n\n- Studio’s spec editor now preloads Monaco with ambient declarations for `@lssm/lib.contracts` and `zod`, so snippets receive autocomplete and inline errors even before the spec ships to the backend. The helper lives in `presentation/components/studio/organisms/monaco-spec-types.ts` and registers the extra libs once per browser session via `monaco.languages.typescript.typescriptDefaults.addExtraLib`.\n- Compiler options are aligned with our frontend toolchain (ES2020 + React JSX) which means drafts written in the editor behave like the compiled artifacts that flow through Studio pipelines.\n\n### Spec templates\n\n- Selecting a spec type now injects a ready-to-edit scaffold (capability, workflow, policy, dataview, component) so authors start from a canonical layout instead of a blank file. Templates live alongside `SpecEditor.tsx`, and we only overwrite the content when the previous value is empty or when the author explicitly switches types via the dropdown.\n\n### Spec preview\n\n- The validation side panel now embeds a `SpecPreview` widget that shows validation errors alongside transport artifacts (GraphQL schema, REST endpoints, component summaries) once a preview run completes. Tabs let authors toggle between “Validation” and “Artifacts,” mirroring the UX described in the Studio plan.\n\n### Testing\n\n- `src/templates/__tests__/runtime.test.ts` covers todos CRUD, messaging delivery, and recipe locale switching through the local GraphQL API.\n- Studio infrastructure tests live in `src/__tests__/e2e/project-lifecycle.test.ts` and continue to exercise project creation + deploy flows.\n\n### Next Steps\n\nFuture templates can register their React components via `registerTemplateComponents(templateId, components)` so TemplateShell can render them automatically. When new templates are added, remember to:\n\n1. Update the registry entry (schema + tags).\n2. Register components inside `presentation/components/templates`.\n3. Document the template under `docs/templates/`.\n\n\n\n\n\n"
+}];
+registerDocBlocks(tech_templates_runtime_DocBlocks);
+
+//#endregion

package/dist/libs/contracts/dist/docs/tech/vscode-extension.docblock.js

@@ -0,0 +1,101 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region ../../libs/contracts/dist/docs/tech/vscode-extension.docblock.js
+const tech_vscode_extension_DocBlocks = [{
+	id: "docs.tech.vscode.extension",
+	title: "ContractSpec VS Code Extension",
+	summary: "VS Code extension for spec-first development with validation, scaffolding, and MCP integration.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/vscode/extension",
+	tags: [
+		"vscode",
+		"extension",
+		"tooling",
+		"dx"
+	],
+	body: `# ContractSpec VS Code Extension
+
+The ContractSpec VS Code extension provides spec-first development tooling directly in your editor.
+
+## Features
+
+- **Real-time Validation**: Get instant feedback on spec errors and warnings as you save files
+- **Build/Scaffold**: Generate handler and component skeletons from specs (no AI required)
+- **Spec Explorer**: List and navigate all specs in your workspace
+- **Dependency Analysis**: Visualize spec dependencies and detect cycles
+- **MCP Integration**: Search ContractSpec documentation via Model Context Protocol
+- **Snippets**: Code snippets for common ContractSpec patterns
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`ContractSpec: Validate Current Spec\` | Validate the currently open spec file |
+| \`ContractSpec: Validate All Specs\` | Validate all spec files in the workspace |
+| \`ContractSpec: Build/Scaffold\` | Generate handler/component from the current spec |
+| \`ContractSpec: List All Specs\` | Show all specs in the workspace |
+| \`ContractSpec: Analyze Dependencies\` | Analyze and visualize spec dependencies |
+| \`ContractSpec: Search Docs (MCP)\` | Search documentation via MCP |
+
+## Configuration
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| \`contractspec.api.baseUrl\` | Base URL for ContractSpec API (enables MCP + remote telemetry) | \`""\` |
+| \`contractspec.telemetry.posthogHost\` | PostHog host URL for direct telemetry | \`"https://eu.posthog.com"\` |
+| \`contractspec.telemetry.posthogProjectKey\` | PostHog project key for direct telemetry | \`""\` |
+| \`contractspec.validation.onSave\` | Run validation on save | \`true\` |
+| \`contractspec.validation.onOpen\` | Run validation on open | \`true\` |
+
+## Architecture
+
+The extension uses:
+- \`@lssm/module.contractspec-workspace\` for pure analysis + templates
+- \`@lssm/bundle.contractspec-workspace\` for workspace services + adapters
+
+This allows the extension to work without requiring the CLI to be installed.
+
+## Telemetry
+
+The extension uses a hybrid telemetry approach:
+1. If \`contractspec.api.baseUrl\` is configured → send to API \`/api/telemetry/ingest\`
+2. Otherwise → send directly to PostHog (if project key configured)
+
+Telemetry respects VS Code's telemetry settings. No file paths, source code, or PII is collected.
+`
+}, {
+	id: "docs.tech.vscode.snippets",
+	title: "ContractSpec Snippets",
+	summary: "Code snippets for common ContractSpec patterns in VS Code.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/vscode/snippets",
+	tags: [
+		"vscode",
+		"snippets",
+		"dx"
+	],
+	body: `# ContractSpec Snippets
+
+The VS Code extension includes snippets for common ContractSpec patterns.
+
+## Available Snippets
+
+| Prefix | Description |
+|--------|-------------|
+| \`contractspec-command\` | Create a new command (write operation) |
+| \`contractspec-query\` | Create a new query (read-only operation) |
+| \`contractspec-event\` | Create a new event |
+| \`contractspec-docblock\` | Create a new DocBlock |
+| \`contractspec-telemetry\` | Create a new TelemetrySpec |
+| \`contractspec-presentation\` | Create a new Presentation |
+
+## Usage
+
+Type the prefix in a TypeScript file and press Tab to expand the snippet. Tab through the placeholders to fill in your values.
+`
+}];
+registerDocBlocks(tech_vscode_extension_DocBlocks);
+
+//#endregion

package/dist/libs/contracts/dist/docs/tech/workflows/overview.docblock.js

@@ -0,0 +1,20 @@
+import { registerDocBlocks } from "../../registry.js";
+
+//#region ../../libs/contracts/dist/docs/tech/workflows/overview.docblock.js
+const tech_workflows_overview_DocBlocks = [{
+	id: "docs.tech.workflows.overview",
+	title: "WorkflowSpec Overview",
+	summary: "WorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@lssm/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/workflows/overview",
+	tags: [
+		"tech",
+		"workflows",
+		"overview"
+	],
+	body: "# WorkflowSpec Overview\n\n## Purpose\n\nWorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@lssm/lib.contracts` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.\n\n## Core Types\n\n- `WorkflowMeta`: ownership metadata (`title`, `domain`, `owners`, `tags`, `stability`) plus `name` and `version`.\n- `WorkflowDefinition`:\n  - `entryStepId?`: optional explicit entry point (defaults to first step).\n  - `steps[]`: ordered list of `Step` descriptors.\n  - `transitions[]`: directed edges between steps with optional expressions.\n  - `sla?`: aggregated timing hints for the overall flow or per-step budgets.\n  - `compensation?`: fallback operations executed when a workflow is rolled back or fails.\n- `Step`:\n  - `type`: `human`, `automation`, or `decision`.\n  - `action`: references either a `ContractSpec` (`operation`) or `FormSpec` (`form`).\n  - Optional `guard`, `timeoutMs`, and retry policy (`maxAttempts`, `backoff`, `delayMs`, `maxDelayMs?`).\n  - `requiredIntegrations?`: integration slot ids that must be bound before the step may execute.\n  - `requiredCapabilities?`: `CapabilityRef[]` that must be enabled in the resolved app config.\n- `Transition`: `from` → `to` with optional `condition` string (simple data expressions).\n\n## Registry & Validation\n\n- `WorkflowRegistry` (`src/workflow/spec.ts`) stores specs by key `<name>.v<version>` and exposes `register`, `list`, and `get`.\n- `validateWorkflowSpec()` (`src/workflow/validation.ts`) checks:\n  - Duplicate step IDs.\n  - Unknown `from`/`to` transitions.\n  - Empty guards/conditions.\n  - Reachability from the entry step.\n  - Cycles in the graph.\n  - Operation/Form references against provided registries.\n- `assertWorkflowSpecValid()` wraps validation and throws `WorkflowValidationError` when errors remain.\n\n## Runtime\n\n- `WorkflowRunner` (`src/workflow/runner.ts`) executes workflows and coordinates steps.\n  - `start(name, version?, initialData?)` returns a `workflowId`.\n  - `executeStep(workflowId, input?)` runs the current step (automation or human).\n  - `getState(workflowId)` retrieves the latest state snapshot.\n  - `cancel(workflowId)` marks the workflow as cancelled.\n  - `preFlightCheck(name, version?, resolvedConfig?)` evaluates integration/capability requirements before the workflow starts.\n  - Throws `WorkflowPreFlightError` if required integration slots are unbound or required capabilities are disabled.\n- `StateStore` (`src/workflow/state.ts`) abstracts persistence. V1 ships with:\n  - `InMemoryStateStore` (`src/workflow/adapters/memory-store.ts`) for tests/dev.\n  - Placeholder factories for file/database adapters (`adapters/file-adapter.ts`, `adapters/db-adapter.ts`).\n- Guard evaluation: expression guards run through `evaluateExpression()` (`src/workflow/expression.ts`); custom policy guards can be provided via `guardEvaluator`.\n- Events: the runner emits `workflow.started`, `workflow.step_completed`, `workflow.step_failed`, and `workflow.cancelled` through the optional `eventEmitter`.\n- React bindings (`@lssm/lib.presentation-runtime-react`):\n  - `useWorkflow` hook (polls state, exposes `executeStep`, `cancel`, `refresh`).\n  - `WorkflowStepper` progress indicator using design-system Stepper.\n  - `WorkflowStepRenderer` helper to render human/automation/decision steps with sensible fallbacks.\n\n## Authoring Checklist\n\n1. Reuse existing operations/forms; create new specs when missing.\n2. Prefer explicit `entryStepId` for clarity (especially with decision branches).\n3. Give automation steps an `operation` and human steps a `form` (warnings surface otherwise).\n4. Use short, meaningful step IDs (`submit`, `review`, `finalize`) to simplify analytics.\n5. Keep guard expressions deterministic; complex policy logic should move to PolicySpec (Phase 2).\n\n## Testing\n\n- Add unit tests for new workflows via `assertWorkflowSpecValid`.\n- Use the new Vitest suites (`validation.test.ts`, `expression.test.ts`, `runner.test.ts`) as examples.\n- CLI support will arrive in Phase 1 PR 3 (`contractspec create --type workflow`).\n\n## Tooling\n\n- `contractspec create --type workflow` scaffolds a WorkflowSpec with interactive prompts.\n- `contractspec build <spec.workflow.ts>` generates a runner scaffold (`.runner.ts`) wired to `WorkflowRunner` and the in-memory store.\n- `contractspec validate` understands `.workflow.ts` files and checks core structure (meta, steps, transitions).\n\n## Next Steps (Non-MVP)\n\n- Persistence adapters (database/file) for workflow state (Phase 2).\n- React bindings (`useWorkflow`, `WorkflowStepper`) and presentation-runtime integration (PR 3).\n- Policy engine integration (`guard.type === 'policy'` validated against PolicySpec).\n- Telemetry hooks for step execution metrics.\n\n"
+}];
+registerDocBlocks(tech_workflows_overview_DocBlocks);
+
+//#endregion

package/dist/{track-PgA6pTIr.d.mts → track.d.ts}

@@ -4,4 +4,4 @@ import { LearningJourneyTrackSpec } from "@lssm/module.learning-journey/track-sp
 declare const drillsLanguageBasicsTrack: LearningJourneyTrackSpec;
 declare const drillTracks: LearningJourneyTrackSpec[];
 //#endregion
-export { drillsLanguageBasicsTrack as n, drillTracks as t };
+export { drillTracks, drillsLanguageBasicsTrack };

package/dist/{track-DuxJHlQ1.mjs → track.js}

@@ -62,4 +62,4 @@ const drillsLanguageBasicsTrack = {
 const drillTracks = [drillsLanguageBasicsTrack];
 
 //#endregion
-export { drillsLanguageBasicsTrack as n, drillTracks as t };
+export { drillTracks, drillsLanguageBasicsTrack };

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@lssm/example.learning-journey-duo-drills",
-  "version": "0.0.0-canary-20251217080011",
+  "version": "0.0.0-canary-20251217083314",
   "description": "Drill-based learning journey example with SRS, XP, and streak hooks.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./example": "./src/example.ts",
-    "./track": "./src/track.ts",
-    "./docs": "./src/docs/index.ts",
-    "./docs/duo-drills.docblock": "./src/docs/duo-drills.docblock.ts",
+    ".": "./dist/index.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/duo-drills.docblock": "./dist/docs/duo-drills.docblock.js",
+    "./example": "./dist/example.js",
+    "./track": "./dist/track.js",
     "./*": "./*"
   },
   "scripts": {
@@ -27,13 +27,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@lssm/module.learning-journey": "0.0.0-canary-20251217080011",
-    "@lssm/lib.schema": "0.0.0-canary-20251217080011",
-    "@lssm/lib.contracts": "0.0.0-canary-20251217080011"
+    "@lssm/module.learning-journey": "0.0.0-canary-20251217083314",
+    "@lssm/lib.schema": "0.0.0-canary-20251217083314",
+    "@lssm/lib.contracts": "0.0.0-canary-20251217083314"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251217080011",
-    "@lssm/tool.typescript": "0.0.0-canary-20251217080011",
+    "@lssm/tool.tsdown": "0.0.0-canary-20251217083314",
+    "@lssm/tool.typescript": "0.0.0-canary-20251217083314",
     "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },

package/tsdown.config.js

@@ -1,13 +1,17 @@
 import { defineConfig } from 'tsdown';
+import { moduleLibrary, withDevExports } from '@lssm/tool.tsdown';
+
+export default defineConfig(() => ({
+  ...moduleLibrary,
+  ...withDevExports,
+}));
+
+
+
+
+
+
+
+
+
 
-export default defineConfig({
-  entry: [
-    'src/index.ts',
-    'src/track.ts',
-    'src/docs/index.ts',
-    'src/docs/duo-drills.docblock.ts',
-  ],
-  format: 'esm',
-  target: 'esnext',
-  dts: true,
-});

package/dist/docs/duo-drills.docblock.mjs

@@ -1,3 +0,0 @@
-import "../duo-drills.docblock-Df751ptb.mjs";
-
-export {  };

package/dist/docs/index.mjs

@@ -1,3 +0,0 @@
-import "../duo-drills.docblock-Df751ptb.mjs";
-
-export {  };

package/dist/duo-drills.docblock--Zt4euaY.d.mts

@@ -1 +0,0 @@
-export { };

package/dist/track.d.mts

@@ -1,2 +0,0 @@
-import { n as drillsLanguageBasicsTrack, t as drillTracks } from "./track-PgA6pTIr.mjs";
-export { drillTracks, drillsLanguageBasicsTrack };

package/dist/track.mjs

@@ -1,3 +0,0 @@
-import { n as drillsLanguageBasicsTrack, t as drillTracks } from "./track-DuxJHlQ1.mjs";
-
-export { drillTracks, drillsLanguageBasicsTrack };