MCard Studio

The HMI and Presentation Membrane for a Personal Knowledge Container

MCard Studio is a spatial web workbench for browsing, editing, and interacting with content-addressed knowledge artifacts. It is the presentation/HMI layer for a local Personal Knowledge Container (PKC), built on published clm-kernel APIs. The Studio UI is not itself the authoritative PKC storage kernel, and this repository does not yet implement a complete authenticated global mesh.

The application separates pure models and projections from UI, client effects, lifecycle wiring, and Node server/storage adapters. Architectural and mathematical terms such as “polynomial interface,” “VCard sandwich,” or “Software Lagrangian” are design models unless a linked interface, guard, or test establishes a concrete behavior.

Current Stack

| Area | Current dependency/configuration | | --- | --- | | SSR/web | Astro 7.3.5, @astrojs/node | | UI | React 19, Dockview React 8.3.1 | | Build | Vite 8.3.1, TypeScript 5.9.3 | | Kernel | clm-kernel 0.0.3 | | Server storage | Node 22 node:sqlite through SqliteNodeEngine and NodeSqliteBackend | | Browser persistence | IndexedDB for VFS workspace persistence | | Tests | Vitest and Playwright | | Optional integrations | Tauri v2, MinIO/S3 client, IPFS HTTP API, local/remote LLM providers |

Application Boundaries

Human / Agent
     │ actions and rendered state
     ▼
MCard Studio HMI ──► core models and projections
     │                       ▲
     ├── edge adapters ──────┤
     ├── membrane wiring ────┤
     └── Node server ────────┴── clm-kernel and local persistence

| Source area | Responsibility | | --- | --- | | src/core/ | Pure models, intents, events, reducers, and projections. | | src/ui/ | Presentation components driven by state and intent callbacks. | | src/edge/ | Browser/client effect adapters and BFF/host clients. | | src/membrane/ | SPEC-302/Cordis lifecycle wiring. | | src/server/ | Node-only API, runtime, repository, ingestion, and storage adapters. | | src/fiber/ | PTR transition adapter, savepoint helper, and trace model. | | src/packages/mcard-studio/ | Zero-DOM published presentation library. |

The static guards check selected import, side-effect, viewlet, path, dependency, and LOC constraints. See npm run check:gates for the current gate battery; a passing guard is not a proof of every theoretical invariant.

What the Application Provides

• Spatial workbench built around Dockview, panels, viewlets, and artifact navigation.
• Terminal modes for browser WASM, JavaScript console, server PTY, and CLM CLI dispatch where configured.
• Chat and model integrations through the Koishi/context layer and configured local/remote providers.
• Card VFS using clm-kernel, server-side artifact collections, and browser workspace persistence.
• Visual authoring/rendering for supported Markdown, Mermaid, TikZ, and other registered content types.
• Multi-card navigation & CLM registry absorption (SMR-10): unified function explorer (src/components/studio/views/functions/), navigation views (views/navigation/), ClmRegistryComponentViewlet, and pure catalog/collection projections (src/core/projection/).
• Refinement inspectors (SMR-11): fibration-dashboard, petri-inspector, and sprint-governance viewlets (src/ui/viewlets/) over pure refinement engines (src/core/refinement/ — Software Lagrangian, Suh coupling, Leinster–Cobbold diversity); read-only by contract.
• Responsive Viewport Lab (SMR-12): pcard:render/viewport-lab — a Single-Device stage and a synchronized Quad-Device Matrix (Wearable 198×242/368×448, Cellphone 375×812/390×844, Laptop 1366×768/1440×900, Desktop 1920×1080/2560×1440) with 90° orientation swap, CSS breakpoint rulers, touch-target heatmaps, and 1-click conformance witness sealing. The archetype registry (src/core/viewport/deviceArchetypeRegistry.ts) and its auditor (viewportAudit.ts) are pure and zero-DOM; WebappZenViewlet exposes all eight presets plus "Open in Responsive Lab". Browser verification runs against loopback fixtures and never contacts a public portal.
• Tauri and PWA configuration with host-specific behavior and optional sync services.

Feature coverage varies by host, configuration, and installed service. Consult the relevant spec and source path before relying on a capability.

Persistence Boundaries

| Boundary | Current role | | --- | --- | | servermemory.db | Authoritative server-side card collection and handle history, using Node node:sqlite. | | Browser clm_workbench_db | IndexedDB database used by src/services/vfs/vfsPersistence.ts for browser workspace persistence. browsermemory.db is a logical collection label, not a SQLite/WASM file in this adapter. | | .clm/content_memory.db | Configured path for the Studio VFS; backend selection depends on host/runtime. | | execution_log.db | Configured collection for supported execution-result records. It does not imply every command is logged. | | MinIO and IPFS | Optional services called by explicit integration paths; neither is an automatic replica for every card. |

The canonical core SQL schema has card, handle_registry, and handle_history. Its documentation link is a symlink to MCard_TDD/schema/mcard_schema.sql in the parent workspace. See docs/schema/README.md and persistence boundaries.

Mesh and Identity Status

The repository includes LAN discovery with mDNS service _pkc._tcp.local., WebSocket get_peers/webrtc_signal signalling, a WebRTC peer-runtime utility, and an IPFS HTTP API client. These pieces do not by themselves provide global DHT discovery, consensus, automatic IPFS replication, or authenticated peer identity. The WebSocket identify handler binds a client-supplied DID string without proving key possession. Noise XX and WireGuard remain target options, not current capabilities.

Get Started

Requirements: Node.js 22 or newer and npm.

npm install
npm run dev

The development script starts the Astro server and WebSocket service. Defaults are http://localhost:5320 and port 5321; check startup output and local configuration if overridden.

As an npm package

The repository also builds a runnable mcard-studio package (currently 0.0.1, MIT) with a CLI. In any consumer project:

npm install mcard-studio        # plus react/react-dom ^19 peers
npx mcard-studio init --apply   # merge dev/start scripts into your package.json
npm run dev                     # or: npx mcard-studio dev

init previews host-script changes without writing; --apply is explicit and conflict-safe. Data stays under the consumer project — nothing writes inside node_modules. Build and verify the artifact yourself with npm run build:npm-app and npm run test:consumer-package (26 checks against the real .tgz outside this repo). See the npm install guide and release checklist. The package is not yet published — registry publication is owner-gated.

Verify Changes

npm run check:gates
npm test
npx playwright test

npm run check runs the configured static gates, style checks, hermetic check, unit tests, build, and smoke test. Test counts and historical pass reports are snapshots; use current command output for release decisions. See docs/guides/RUN_TESTS.md.

For desktop development/build, use npm run tauri:dev and npm run tauri:build. The repository Compose configuration is a development/deployment template, not a production-readiness guarantee. Review Production Deployment and set deployment-specific secrets before exposing any services.

Documentation

• Documentation home and complete index
• Architecture and schema/runtime inventory
• Engineering conventions
• Functionality specifications
• Guides and operations
• Sprint roadmap, including graduated Program MI documentation

Design Vocabulary

The polynomial normal form $p(y)=\sum_{s\in p(1)}y^{p[s]}$ describes positions and their available directions as a design model. MCard/PCard/VCard roles are artifacts, processes, and witnesses; they are not a literal SQL type isomorphism. Baldwin's Splitting, Substituting, Augmenting, Excluding, Inverting, and Porting are useful design-review labels, not runtime operations automatically executed by the application.