@inharness-ai/claude4spec 1.0.21 → 1.0.23

package/dist/shared/plugin-host/frontend-manifest.js

@@ -0,0 +1,89 @@
+/**
+ * M33 — frontend plugin loading contract ("Option B": import map + native ESM).
+ *
+ * The client fetches {@link FrontendManifestResponse} at boot, injects an
+ * import map (so plugin `import "react"` resolves to the host's singleton),
+ * injects each plugin's CSS, then `await import(entry)` per active plugin.
+ *
+ * Shared so the server builder and the client boot loader agree on the shape.
+ */
+/**
+ * Bare specifiers the import map externalizes to host-served shim ESM modules.
+ * Each resolves to `/api/plugins/runtime/<peer>.js`, which re-exports the host's
+ * live singleton from `window.__c4s_shared`. Keeping the list here lets the
+ * server builder and the client publisher stay in lockstep.
+ */
+export const SHARED_PEER_SPECIFIERS = [
+    'react',
+    // The automatic JSX runtime subpaths a plugin's `dist/frontend.js` emits when
+    // compiled with `jsx: 'react-jsx'` (`import { jsx, jsxs } from "react/jsx-runtime"`,
+    // dev builds also `jsxDEV` from `react/jsx-dev-runtime`). These are SEPARATE bare
+    // subpaths not covered by the `react` entry, so they need their own import-map
+    // entries — otherwise the browser can't resolve them and the whole plugin module
+    // fails to load. Sharing them keeps the plugin on the host's single React
+    // reconciler (L11 invariant) instead of bundling a second copy.
+    'react/jsx-runtime',
+    'react/jsx-dev-runtime',
+    'react-dom',
+    'react-dom/client',
+    '@tiptap/core',
+    '@tanstack/react-query',
+    // M33 phase 3: the router is a SHARED library peer (one instance via the import
+    // map) so a plugin's `createRoute({ getParentRoute })` and the host's single
+    // TanStack Router operate on the SAME route-tree types — NOT a live singleton
+    // re-exported through `@c4s/plugin-runtime`.
+    '@tanstack/react-router',
+    '@c4s/plugin-runtime',
+    '@c4s/plugin-runtime/ui',
+];
+/**
+ * The value exports of `@c4s/plugin-runtime` (frontend facade), the one peer the
+ * server can't introspect by importing (it's a browser module). The runtime
+ * shim generator emits these names; a parity test asserts they match the actual
+ * module so this list can't silently drift. Keep in sync with
+ * `src/client/runtime/plugin-runtime.ts` value exports.
+ */
+export const PLUGIN_RUNTIME_EXPORT_NAMES = [
+    'clientPluginHost',
+    'registerFrontendModule',
+    'queryClient',
+    'editorBridge',
+    'registerExtensionReferenceType',
+    'HOST_API_VERSION',
+];
+/**
+ * The VALUE exports of `@c4s/plugin-runtime/ui` (Host UI Kit catalog, M34/L12) —
+ * a browser module the server can't introspect, same as the main facade above.
+ * The runtime shim emits these names; a parity test asserts they match the
+ * actual module so this list can't silently drift. Keep in sync with
+ * `src/client/runtime/plugin-runtime-ui.ts` (→ `client/host-ui-kit/index.ts`)
+ * value exports. Type-only exports are erased at runtime and excluded here.
+ */
+export const PLUGIN_RUNTIME_UI_EXPORT_NAMES = [
+    // Core (stable)
+    'EntityListHeader',
+    'DetailPanelShell',
+    'FieldRow',
+    'FieldGrid',
+    // List (experimental)
+    'EntityListLayout',
+    'Pagination',
+    'EmptyState',
+    'TagFilterBar',
+    'EntityListRow',
+    // Actions & states (experimental)
+    'ActionButton',
+    'Badge',
+    'LoadingState',
+    // Form (experimental)
+    'FormField',
+    'InlineEditField',
+    // Token bridge
+    'useHostTokens',
+    'HOST_TOKEN_NAMES',
+    'readHostTokens',
+    // Stability metadata
+    'UI_KIT_CATALOG',
+    'STABLE_UI_KIT_COMPONENTS',
+];
+//# sourceMappingURL=frontend-manifest.js.map

package/dist/shared/plugin-host/frontend-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-manifest.js","sourceRoot":"","sources":["../../../src/shared/plugin-host/frontend-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA0BH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,OAAO;IACP,8EAA8E;IAC9E,qFAAqF;IACrF,kFAAkF;IAClF,+EAA+E;IAC/E,iFAAiF;IACjF,0EAA0E;IAC1E,gEAAgE;IAChE,mBAAmB;IACnB,uBAAuB;IACvB,WAAW;IACX,kBAAkB;IAClB,cAAc;IACd,uBAAuB;IACvB,gFAAgF;IAChF,6EAA6E;IAC7E,8EAA8E;IAC9E,6CAA6C;IAC7C,wBAAwB;IACxB,qBAAqB;IACrB,wBAAwB;CAChB,CAAC;AAIX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,kBAAkB;IAClB,wBAAwB;IACxB,aAAa;IACb,cAAc;IACd,gCAAgC;IAChC,kBAAkB;CACV,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,gBAAgB;IAChB,kBAAkB;IAClB,kBAAkB;IAClB,UAAU;IACV,WAAW;IACX,sBAAsB;IACtB,kBAAkB;IAClB,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,eAAe;IACf,kCAAkC;IAClC,cAAc;IACd,OAAO;IACP,cAAc;IACd,sBAAsB;IACtB,WAAW;IACX,iBAAiB;IACjB,eAAe;IACf,eAAe;IACf,kBAAkB;IAClB,gBAAgB;IAChB,qBAAqB;IACrB,gBAAgB;IAChB,0BAA0B;CAClB,CAAC"}

package/dist/shared/plugin-host/host-api.d.ts

@@ -0,0 +1,60 @@
+/**
+ * M33 — Host API versioning surface: the per-major changelog and the
+ * migration descriptors a plugin author needs when their package was built
+ * against an incompatible major.
+ *
+ * Versioning rule (mirrored in the manifest doc): additive same-major slots =
+ * minor bump; a breaking slot-shape change = major bump WITH a descriptor here
+ * and a deprecation window (a slot deprecated in major N may be removed only in
+ * N+1). `incompatible` (major mismatch) is distinct from `skipped` (an `engines`
+ * miss — an environment problem with no migration path).
+ *
+ * The surface now also covers the `stable` Host UI Kit components (M34/L12); a
+ * breaking prop-shape change there is a major bump with a `ui-prop-reshape`
+ * descriptor (see {@link VERSIONED_UI_KIT_COMPONENTS}).
+ */
+/**
+ * The component prop contracts counted into the versioned `hostApiVersion`
+ * surface from the Host UI Kit (M34/L12): the `stable` (Core) tier ONLY. A
+ * breaking prop-shape change to one of these is a major bump carrying a
+ * `ui-prop-reshape` descriptor below (AC3). `experimental` kit components are
+ * exposed by `@c4s/plugin-runtime/ui` but excluded here — their props may change
+ * without a major and they are NOT gated at plugin load (AC4). Promoting an
+ * `experimental` component to `stable` adds it to {@link UI_KIT_STABLE_COMPONENTS}
+ * and thereby to this surface (AC5).
+ */
+export declare const VERSIONED_UI_KIT_COMPONENTS: readonly ["EntityListHeader", "DetailPanelShell", "FieldRow", "FieldGrid"];
+/** One versioned change to the Host API contract between two adjacent majors. */
+export interface HostApiMigration {
+    fromMajor: number;
+    toMajor: number;
+    /** The affected slot / surface, e.g. "onUnregister" or a `stable` kit component. */
+    slot: string;
+    /**
+     * `ui-prop-reshape` — a breaking prop-shape change to a `stable` Host UI Kit
+     * component (M34/L12). The others cover the manifest/contributes/editor
+     * surfaces.
+     */
+    kind: 'slot-required' | 'field-rename' | 'contributes-reshape' | 'ui-prop-reshape';
+    /** Human-readable migration instruction. */
+    summary: string;
+}
+/** Migration path attached to an `incompatible` package record. */
+export interface PluginMigrationInfo {
+    /** The Host API version to target after migrating. */
+    targetHostApiVersion: string;
+    /** Versioned descriptors of the shape changes between the plugin's major and the host's. */
+    migrations: HostApiMigration[];
+    /** Whether a compat-shim exists for the deprecated slot(s). */
+    shimAvailable: boolean;
+}
+/** First numeric component of a semver RANGE (e.g. "^1.4.0" → 1, ">=2.5.0" → 2). */
+export declare function rangeMajor(range: string): number | null;
+/** Changelog entries spanning the majors between (inclusive of the boundary crossings). */
+export declare function migrationsBetween(fromMajor: number, toMajor: number): HostApiMigration[];
+/**
+ * Build the migration info for a plugin whose `hostApiVersion` RANGE targets a
+ * different major than the running host. Returns `null` when the majors match
+ * (no migration needed) or the range major is unparseable.
+ */
+export declare function buildMigrationInfo(pluginRange: string): PluginMigrationInfo | null;

package/dist/shared/plugin-host/host-api.js

@@ -0,0 +1,67 @@
+/**
+ * M33 — Host API versioning surface: the per-major changelog and the
+ * migration descriptors a plugin author needs when their package was built
+ * against an incompatible major.
+ *
+ * Versioning rule (mirrored in the manifest doc): additive same-major slots =
+ * minor bump; a breaking slot-shape change = major bump WITH a descriptor here
+ * and a deprecation window (a slot deprecated in major N may be removed only in
+ * N+1). `incompatible` (major mismatch) is distinct from `skipped` (an `engines`
+ * miss — an environment problem with no migration path).
+ *
+ * The surface now also covers the `stable` Host UI Kit components (M34/L12); a
+ * breaking prop-shape change there is a major bump with a `ui-prop-reshape`
+ * descriptor (see {@link VERSIONED_UI_KIT_COMPONENTS}).
+ */
+import { HOST_API_VERSION, parseMajor } from './manifest.js';
+import { UI_KIT_STABLE_COMPONENTS } from './ui-kit-surface.js';
+/**
+ * The component prop contracts counted into the versioned `hostApiVersion`
+ * surface from the Host UI Kit (M34/L12): the `stable` (Core) tier ONLY. A
+ * breaking prop-shape change to one of these is a major bump carrying a
+ * `ui-prop-reshape` descriptor below (AC3). `experimental` kit components are
+ * exposed by `@c4s/plugin-runtime/ui` but excluded here — their props may change
+ * without a major and they are NOT gated at plugin load (AC4). Promoting an
+ * `experimental` component to `stable` adds it to {@link UI_KIT_STABLE_COMPONENTS}
+ * and thereby to this surface (AC5).
+ */
+export const VERSIONED_UI_KIT_COMPONENTS = UI_KIT_STABLE_COMPONENTS;
+/**
+ * The Host API changelog, one entry per breaking change at a major boundary.
+ * Empty at the `1.0.0` baseline — no major has been crossed yet. The first
+ * breaking slot-shape change will add an entry here (and bump the major).
+ */
+const HOST_API_CHANGELOG = [];
+/** First numeric component of a semver RANGE (e.g. "^1.4.0" → 1, ">=2.5.0" → 2). */
+export function rangeMajor(range) {
+    const m = /(\d+)/.exec(range);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return Number.isFinite(n) ? n : null;
+}
+/** Changelog entries spanning the majors between (inclusive of the boundary crossings). */
+export function migrationsBetween(fromMajor, toMajor) {
+    const [lo, hi] = fromMajor <= toMajor ? [fromMajor, toMajor] : [toMajor, fromMajor];
+    return HOST_API_CHANGELOG.filter((m) => m.fromMajor >= lo && m.toMajor <= hi);
+}
+/**
+ * Build the migration info for a plugin whose `hostApiVersion` RANGE targets a
+ * different major than the running host. Returns `null` when the majors match
+ * (no migration needed) or the range major is unparseable.
+ */
+export function buildMigrationInfo(pluginRange) {
+    const pluginMajor = rangeMajor(pluginRange);
+    const hostMajor = parseMajor(HOST_API_VERSION);
+    if (pluginMajor == null || hostMajor == null || pluginMajor === hostMajor)
+        return null;
+    const migrations = migrationsBetween(pluginMajor, hostMajor);
+    return {
+        targetHostApiVersion: HOST_API_VERSION,
+        migrations,
+        // No shim without descriptors, and a slot becoming required can never be
+        // shimmed (the author must implement it). Empty changelog ⇒ false.
+        shimAvailable: migrations.length > 0 && migrations.every((m) => m.kind !== 'slot-required'),
+    };
+}
+//# sourceMappingURL=host-api.js.map

package/dist/shared/plugin-host/host-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-api.js","sourceRoot":"","sources":["../../../src/shared/plugin-host/host-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,wBAAwB,CAAC;AA4BpE;;;;GAIG;AACH,MAAM,kBAAkB,GAAuB,EAAE,CAAC;AAElD,oFAAoF;AACpF,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,OAAe;IAClE,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACpF,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,IAAI,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC/C,IAAI,WAAW,IAAI,IAAI,IAAI,SAAS,IAAI,IAAI,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvF,MAAM,UAAU,GAAG,iBAAiB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC7D,OAAO;QACL,oBAAoB,EAAE,gBAAgB;QACtC,UAAU;QACV,yEAAyE;QACzE,mEAAmE;QACnE,aAAa,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC;KAC5F,CAAC;AACJ,CAAC"}

package/dist/shared/plugin-host/manifest.d.ts

@@ -0,0 +1,194 @@
+/**
+ * M33 — runtime plugin manifest contract.
+ *
+ * A plugin is an npm package that default-exports (or named-exports as
+ * `manifest`) a {@link PluginManifest}. The host loader (`loadWorkspacePlugins`)
+ * dynamic-imports each workspace-declared package, validates `hostApiVersion`
+ * / `engines`, then fans `contributes.entities` out to `registerEntityModule`.
+ *
+ * This lives in `shared/` (not `server/`) because the external `c4s-reader`
+ * and plugin authors need the contract without pulling in express /
+ * better-sqlite3. Server-only payloads (the express Router, the L9 serializer)
+ * are typed `unknown` here and narrowed server-side.
+ */
+import type { EntityModuleManifest, SystemPromptContribution } from './types.js';
+/**
+ * The Host API version this build advertises. Bumped on a breaking change to
+ * any surface counted into the contract: the manifest / EntityModule
+ * signatures, the `mountBackend(app, mcpHost, db, cwd)` mount-context shape,
+ * the chip/card/row prop shapes, the L8 editor registration contract, and the
+ * prop contracts of the `stable` Host UI Kit components (M34/L12;
+ * `@c4s/plugin-runtime/ui`). See `UI_KIT_STABLE_COMPONENTS` in
+ * `ui-kit-surface.ts`; `experimental` kit components are deliberately NOT part
+ * of this surface.
+ *
+ * A plugin whose `hostApiVersion` range does not satisfy this version is
+ * skipped with a warning (never crashed over) — on the backend during load and
+ * independently on the frontend during manifest consumption.
+ *
+ * Versioning rule — only a breaking slot-shape change bumps the version, and it
+ * bumps the MAJOR (with a descriptor in the changelog — see `host-api.ts`); the
+ * loader gate compares majors only. A plugin built against a different major is
+ * reported `incompatible` with a migration descriptor (vs the environment-level
+ * `skipped` for an `engines` miss).
+ *
+ * `1.0.0` baseline — the Host UI Kit catalog + `stable` prop contracts
+ * (`@c4s/plugin-runtime/ui`, M34/L12) shipped WITHIN this major, so they are
+ * folded into the `1.0.0` versioned surface rather than bumping it; no major has
+ * been crossed, so the changelog stays empty.
+ */
+export declare const HOST_API_VERSION = "1.0.0";
+/** Node/host engine constraints — checked by the loader before registration. */
+export interface PluginEngines {
+    /** semver range matched against `process.versions.node`. */
+    node?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Authoring shape for one contributed entity type. A superset of the shared
+ * {@link EntityModuleManifest} carrying the slots the host needs to lower it
+ * into a server `BackendModule`. The express Router (`backend.routes`) and the
+ * L9 serializer are typed `unknown` here so the shared bundle stays dep-free;
+ * the registry narrows them at registration time.
+ */
+export interface EntityContribution extends EntityModuleManifest {
+    /** L9 — JSON serializer (server `EntitySerializer<unknown>`; narrowed server-side). */
+    serializer: unknown;
+    /** M05 — system prompt contribution composed by buildSystemPrompt. */
+    systemPrompt: SystemPromptContribution;
+    backend?: {
+        /** Per-plugin idempotent SQL migrations (server `SqlMigration[]`). */
+        migrations?: unknown[];
+        /**
+         * Full-power imperative mount hook (server `PluginMountFn`). Receives the
+         * MountContext; owns service construction, route mounting, MCP + service
+         * registration. Takes precedence over `routes`.
+         */
+        mount?: unknown;
+        /**
+         * Sugar: a pre-built express Router mounted at `pathPrefix`. When supplied
+         * without `mount`, the registry synthesizes
+         * `mount = (ctx) => ctx.app.use(pathPrefix, routes)` — no MCP server, no
+         * entity service, no migrations.
+         */
+        routes?: unknown;
+    };
+    /** L8 — client editor extensions + render slots (narrowed client-side). */
+    frontend?: unknown;
+}
+/**
+ * Authoring shape for one contributed writing style (M15). A plugin carries the
+ * style inline (body + optional attached files) rather than dropping a SKILL.md
+ * dir on disk — discovery is by push at load time (the loader fans these into
+ * the per-project SkillRegistry as `source: "plugin"`), not by FS scan.
+ */
+export interface WritingStyleContribution {
+    /** Stable identifier; also the dedup key against bundled/user styles. */
+    slug: string;
+    title: string;
+    description: string;
+    /** Positive integer; mirrors SKILL.md frontmatter `version`. */
+    version: number;
+    language: 'en' | 'pl';
+    /** The skill body markdown (the SKILL.md content without frontmatter). */
+    content: string;
+    /** Optional attached files (templates/examples/workflows), keyed by rel path. */
+    files?: Record<string, string>;
+}
+/**
+ * M33 — one settings field a plugin renders in its own Settings section
+ * (panel M26), values stored under `config.plugins[<manifest.name>][key]`.
+ * `kind` drives the reload classification on write:
+ *   - `hot-reload` → only `invalidateQueries(['config'])`, no context rebuild
+ *     (parity with `writingStyle` / `language`; takes effect next turn/thread).
+ *   - `executive` → invalidates the `ProjectContext` (rebuild, no banner, no
+ *     restart).
+ */
+export interface PluginSettingField {
+    /** Stable field key inside the plugin's config namespace. */
+    key: string;
+    /** Human label shown in the Settings panel. */
+    label: string;
+    control: 'toggle' | 'text' | 'select' | 'multiselect';
+    kind: 'hot-reload' | 'executive';
+    /** Default applied when `config.plugins[<name>][key]` is absent. */
+    default: unknown;
+    /** Choices for `select` / `multiselect` controls. */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** Optional help/description text. */
+    help?: string;
+}
+/** A plugin's settings module = an ordered list of fields. */
+export type PluginSettingsModule = PluginSettingField[];
+/**
+ * M33 — declarative editor slash-command contributed by a plugin
+ * (typically an entity-less one). The loader normalizes each entry into an
+ * `EditorExtensionRegistration.slashCommand` and routes it through
+ * `registerEditorExtension(...)` — the SAME path as entity-borne extensions.
+ * Declarative, not imperative: the plugin declares the trigger + popover to
+ * open; execution is the editor framework's popover dispatch, not plugin code.
+ * Kept as a dep-free subset here (the full `EditorExtensionRegistration` lives
+ * client-side); `popoverKind` is narrowed against the client `PopoverMap`.
+ */
+export interface PluginCommandContribution {
+    /** Stable registration name (unique within the editor extension registry). */
+    name: string;
+    /** Slash trigger token, e.g. "mychart". */
+    trigger: string;
+    /** Menu label shown in the slash palette. */
+    label: string;
+    /** Popover kind dispatched on invoke (client `PopoverKind`). */
+    popoverKind: string;
+    /** Editor contexts the command is available in. Omitted = all contexts. */
+    availableIn?: string[];
+}
+/**
+ * The default export of a plugin package. `contributes` is the capability
+ * bundle: `contributes.entities`, `contributes.writingStyles` (pushed into the
+ * SkillRegistry as `source: "plugin"`), and
+ * `contributes.settings` / `contributes.commands`.
+ */
+export interface PluginManifest {
+    /** npm package name. */
+    name: string;
+    /** plugin semver. */
+    version: string;
+    /** semver range — which Host API the plugin targets, e.g. "^1.0.0". */
+    hostApiVersion: string;
+    /** node/host engine constraints. */
+    engines?: PluginEngines;
+    /**
+     * REQUIRED teardown hook, symmetric to backend mount — a required slot from
+     * the `1.0.0` baseline. The hot-reload pipeline calls it on the OLD version
+     * before registering the new one; without it a reload would leave duplicated
+     * slots (MCP server, Express routes, editor extensions, zustand slice). Must
+     * be idempotent and non-throwing — a thrown error is logged as a warning and
+     * never blocks the reload.
+     */
+    onUnregister(): void;
+    contributes: {
+        entities?: EntityContribution[];
+        /** M15 — writing styles contributed by this plugin. */
+        writingStyles?: WritingStyleContribution[];
+        /** M33 — settings fields rendered per-plugin in Settings (M26). */
+        settings?: PluginSettingsModule;
+        /** M33 — declarative editor slash-commands (entity-less plugins). */
+        commands?: PluginCommandContribution[];
+    };
+}
+/** One plugin's Settings section, as returned by `ProjectPluginHost.listSettings()`. */
+export interface PluginSettingsSection {
+    /** Plugin package name — also the `config.plugins` namespace key. */
+    name: string;
+    version: string;
+    fields: PluginSettingsModule;
+}
+/**
+ * Parse the major component of a clean semver string (e.g. "1.4.0" -> 1).
+ * Used for the cheap major-mismatch gate on the frontend, mirroring the
+ * backend's `semver.satisfies` check. Returns `null` for unparseable input.
+ */
+export declare function parseMajor(version: string): number | null;

package/dist/shared/plugin-host/manifest.js

@@ -0,0 +1,52 @@
+/**
+ * M33 — runtime plugin manifest contract.
+ *
+ * A plugin is an npm package that default-exports (or named-exports as
+ * `manifest`) a {@link PluginManifest}. The host loader (`loadWorkspacePlugins`)
+ * dynamic-imports each workspace-declared package, validates `hostApiVersion`
+ * / `engines`, then fans `contributes.entities` out to `registerEntityModule`.
+ *
+ * This lives in `shared/` (not `server/`) because the external `c4s-reader`
+ * and plugin authors need the contract without pulling in express /
+ * better-sqlite3. Server-only payloads (the express Router, the L9 serializer)
+ * are typed `unknown` here and narrowed server-side.
+ */
+/**
+ * The Host API version this build advertises. Bumped on a breaking change to
+ * any surface counted into the contract: the manifest / EntityModule
+ * signatures, the `mountBackend(app, mcpHost, db, cwd)` mount-context shape,
+ * the chip/card/row prop shapes, the L8 editor registration contract, and the
+ * prop contracts of the `stable` Host UI Kit components (M34/L12;
+ * `@c4s/plugin-runtime/ui`). See `UI_KIT_STABLE_COMPONENTS` in
+ * `ui-kit-surface.ts`; `experimental` kit components are deliberately NOT part
+ * of this surface.
+ *
+ * A plugin whose `hostApiVersion` range does not satisfy this version is
+ * skipped with a warning (never crashed over) — on the backend during load and
+ * independently on the frontend during manifest consumption.
+ *
+ * Versioning rule — only a breaking slot-shape change bumps the version, and it
+ * bumps the MAJOR (with a descriptor in the changelog — see `host-api.ts`); the
+ * loader gate compares majors only. A plugin built against a different major is
+ * reported `incompatible` with a migration descriptor (vs the environment-level
+ * `skipped` for an `engines` miss).
+ *
+ * `1.0.0` baseline — the Host UI Kit catalog + `stable` prop contracts
+ * (`@c4s/plugin-runtime/ui`, M34/L12) shipped WITHIN this major, so they are
+ * folded into the `1.0.0` versioned surface rather than bumping it; no major has
+ * been crossed, so the changelog stays empty.
+ */
+export const HOST_API_VERSION = '1.0.0';
+/**
+ * Parse the major component of a clean semver string (e.g. "1.4.0" -> 1).
+ * Used for the cheap major-mismatch gate on the frontend, mirroring the
+ * backend's `semver.satisfies` check. Returns `null` for unparseable input.
+ */
+export function parseMajor(version) {
+    const match = /^\s*v?(\d+)\./.exec(version);
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    return Number.isFinite(major) ? major : null;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/shared/plugin-host/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/shared/plugin-host/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;AA8JxC;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC"}

package/dist/shared/plugin-host/ui-kit-surface.d.ts

@@ -0,0 +1,22 @@
+/**
+ * M34 / L12 ↔ L11 — the versioned slice of the Host UI Kit.
+ *
+ * React-free so both the server (`server/plugin-runtime/ui.ts`) and the version
+ * surface (`host-api.ts`) can reference it without importing the client catalog
+ * (which pulls in React). The client catalog (`client/host-ui-kit/registry.ts`)
+ * derives the SAME stable set from the components' field-level `stability`
+ * constants; a test asserts the two agree, so this list can't silently drift
+ * from the actual components.
+ */
+/** Per-component stability tier. */
+export type Stability = 'stable' | 'experimental';
+/**
+ * The catalog components whose prop contracts are part of the versioned
+ * `hostApiVersion` surface — the `stable` (Core) tier only. A breaking
+ * prop-shape change to any of these requires a major `hostApiVersion` bump + a
+ * `migrations[]` descriptor (see {@link file://./host-api.ts}). `experimental`
+ * components are exposed by `/ui` but excluded from the surface; promoting one
+ * to `stable` adds it here.
+ */
+export declare const UI_KIT_STABLE_COMPONENTS: readonly ["EntityListHeader", "DetailPanelShell", "FieldRow", "FieldGrid"];
+export type StableUiKitComponent = (typeof UI_KIT_STABLE_COMPONENTS)[number];

package/dist/shared/plugin-host/ui-kit-surface.js

@@ -0,0 +1,25 @@
+/**
+ * M34 / L12 ↔ L11 — the versioned slice of the Host UI Kit.
+ *
+ * React-free so both the server (`server/plugin-runtime/ui.ts`) and the version
+ * surface (`host-api.ts`) can reference it without importing the client catalog
+ * (which pulls in React). The client catalog (`client/host-ui-kit/registry.ts`)
+ * derives the SAME stable set from the components' field-level `stability`
+ * constants; a test asserts the two agree, so this list can't silently drift
+ * from the actual components.
+ */
+/**
+ * The catalog components whose prop contracts are part of the versioned
+ * `hostApiVersion` surface — the `stable` (Core) tier only. A breaking
+ * prop-shape change to any of these requires a major `hostApiVersion` bump + a
+ * `migrations[]` descriptor (see {@link file://./host-api.ts}). `experimental`
+ * components are exposed by `/ui` but excluded from the surface; promoting one
+ * to `stable` adds it here.
+ */
+export const UI_KIT_STABLE_COMPONENTS = [
+    'EntityListHeader',
+    'DetailPanelShell',
+    'FieldRow',
+    'FieldGrid',
+];
+//# sourceMappingURL=ui-kit-surface.js.map

package/dist/shared/plugin-host/ui-kit-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-kit-surface.js","sourceRoot":"","sources":["../../../src/shared/plugin-host/ui-kit-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,kBAAkB;IAClB,kBAAkB;IAClB,UAAU;IACV,WAAW;CACH,CAAC"}

package/dist/shared/types.d.ts

@@ -85,6 +85,11 @@ export type WsEvent = {
     ts: number;
 } | {
     kind: 'project:disposed';
+} | {
+    kind: 'plugin:reloaded';
+    name: string;
+    version: string;
+    tier: 'base' | 'overlay';
 };
 /** M02 multidir: discriminator dla source-of-truth (pagesDir / briefsDir / patchesDir). */
 export type PagesRootDir = 'pages' | 'briefs' | 'patches';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inharness-ai/claude4spec",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "Plan the whole system before your agent writes a line of code. Local-first planning layer with structured entities and typed relations.",
   "license": "MIT",
   "author": "Mike Tomala <mike@inharness.ai>",
@@ -38,15 +38,28 @@
     "c4s": "dist/bin/c4s.js",
     "c4s-mcp": "dist/bin/c4s-mcp.js"
   },
+  "exports": {
+    "./package.json": "./package.json",
+    "./plugin-runtime": {
+      "types": "./dist/plugin-types/plugin-runtime.d.ts"
+    },
+    "./plugin-runtime/ui": {
+      "types": "./dist/plugin-types/ui.d.ts"
+    },
+    "./plugin-runtime/ambient": {
+      "types": "./dist/plugin-types/ambient.d.ts"
+    }
+  },
   "scripts": {
     "dev": "tsx watch src/bin/claude4spec.ts --mode dev",
     "dev:sandbox": "tsx watch src/bin/claude4spec.ts --mode dev --cwd .claude/skills/specyfikacja --pages .",
     "c4s": "tsx src/bin/c4s.ts",
     "build:server": "tsc -p tsconfig.server.json && rm -rf dist/server/db/migrations && cp -R src/server/db/migrations dist/server/db/migrations && rm -rf dist/server/skills && cp -R src/server/skills dist/server/skills && chmod +x dist/bin/claude4spec.js dist/bin/c4s.js dist/bin/c4s-mcp.js",
     "build:client": "vite build",
-    "build": "npm run build:client && npm run build:server",
+    "build:types": "tsc -p tsconfig.types.json && cp src/plugin-types/ambient.d.ts dist/plugin-types/ambient.d.ts",
+    "build": "npm run build:client && npm run build:server && npm run build:types",
     "start": "node dist/bin/claude4spec.js",
-    "typecheck": "tsc -p tsconfig.server.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "typecheck": "tsc -p tsconfig.server.json --noEmit && tsc -p tsconfig.client.json --noEmit && tsc -p tsconfig.types.json --noEmit",
     "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -78,6 +91,7 @@
     "@tiptap/suggestion": "^2.27.2",
     "@types/diff": "^7.0.2",
     "better-sqlite3": "^11.7.0",
+    "@inharness-ai/c4s-plugin-simple-database-tables": "^0.1.0",
     "chokidar": "^4.0.3",
     "diff": "^9.0.0",
     "express": "^4.21.2",
@@ -91,6 +105,7 @@
     "react-markdown": "^9.1.0",
     "rehype-highlight": "^7.0.2",
     "remark-gfm": "^4.0.1",
+    "semver": "^6.3.1",
     "tar": "^7.5.15",
     "tiptap-markdown": "^0.8.10",
     "ws": "^8.18.0",

package/dist/client/assets/channel-D5gzBvo7.js

@@ -1 +0,0 @@
-import{ai as o,aj as n}from"./mermaid.core-C29eoXRj.js";const t=(a,r)=>o.lang.round(n.parse(a)[r]);export{t as c};

package/dist/client/assets/classDiagram-4FO5ZUOK-CT-amIxa.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-DRchPPRe.js";import{_ as i}from"./mermaid.core-C29eoXRj.js";import"./chunk-FMBD7UC4-p2tIiP1D.js";import"./chunk-ND2GUHAM-B1mbl2hP.js";import"./chunk-55IACEB6-CxrIbZhB.js";import"./chunk-2J33WTMH-BnS95YpK.js";import"./index-DyAnw7YN.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/client/assets/classDiagram-v2-Q7XG4LA2-CT-amIxa.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-DRchPPRe.js";import{_ as i}from"./mermaid.core-C29eoXRj.js";import"./chunk-FMBD7UC4-p2tIiP1D.js";import"./chunk-ND2GUHAM-B1mbl2hP.js";import"./chunk-55IACEB6-CxrIbZhB.js";import"./chunk-2J33WTMH-BnS95YpK.js";import"./index-DyAnw7YN.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};