entangled-worlds-orbiters-shared 2.9.1 → 2.11.0

package/README.md

@@ -71,6 +71,32 @@ import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
 ### Configuration
 - `textureConfig` - Texture configuration system
 
+### Star (`entangled-worlds-orbiters-shared/star`)
+- `createStar`, `StarManager` - The host star of a world: single, binary or trinary, emissive, shader-only glow (two draw calls for any multiplicity; lights nothing)
+- `DEFAULT_STAR_PARAMS`, `normalizeStarParams` - Author params (temperature, radius, luminosity, activity, multiplicity, separation, seed, placement) + validator for stored params
+- `starParamsFromStellarData` - Catalogue host-star data (Teff, radius, mass, luminosity, spectral type, star count or a "(AB)b" name suffix) → params
+- `blackbodyColor`, `spectralClass`, `starLayout`, `starPositions` - Pure colour / layout / orbit helpers
+- `getFocus` (on `createStar` / `StarManager`), `framingDistance`, `defaultStarPlacement` - Camera focus on the system barycentre and host-camera-aware placement
+- The star lights the scene: `StarManager` key + camera-side fill lights, `setLighting`, `lightingFromLegacy`, `DEFAULT_AMBIENT` (pair with `setHemisphereEnabled(scene, false)` from `./core`; moons `emissiveLift`, GLB `emissiveIntensity` for night sides)
+- Real binaries (close pair from component masses, a distant companion for wide pairs) and an optional debris disc; `mainSequenceTemperature` / `Radius` / `Luminosity` helpers
+- Perf + look harness: `npm run bench:star` (see `bench/star/results/REPORT.md`)
+
+### Capabilities (`entangled-worlds-orbiters-shared/capabilities`)
+- `createCapabilityRegistry` - Validated, named registry of studio actions (query / mutation / generative)
+- `validate`, `assertValid` - JSON-Schema-subset validator used for capability inputs
+- Error taxonomy - `ValidationError`, `UnavailableError`, `PrecheckError`, …
+
+### Studio session (`entangled-worlds-orbiters-shared/studio`)
+- `createHistory` - Snapshot undo/redo with injected snapshot/restore
+- `createAutosaveSession` - Debounced autosave state machine (dirty / in flight / queued / host ack)
+- `createPatchStore`, `makeHeaderBroadcast` - Header mirror for a UI that mounts after the controller
+- `createStatusChannel` - Status-line seam ("Saving…", "Saved")
+- `isTrustedHostOrigin`, `isEmbedded`, `postToHost` - Host-frame transport
+
+### Uploads (`entangled-worlds-orbiters-shared/uploads`)
+- `uploadViaSignedUrl` - The API's signed-URL upload: `/spaces/upload-init` → PUT → `/spaces/upload-complete`, over the app's own authenticated JSON caller
+- `putToSignedUrl` - The storage PUT alone, with progress and abort
+
 ## Runtime base configuration (env)
 
 This package is built statically. At runtime, it can use a public base URL to turn relative asset paths into absolute URLs. If you don’t provide a base, it will use same-origin root-relative paths (e.g., `/default/...`).

package/dist/capabilities/errors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Capability layer error taxonomy (shared machinery).
+ *
+ * This is the ONE generic capability machinery, app-agnostic and layer-neutral
+ * (`src/capabilities/` imports nothing app-level — see `.agents/decisions/`). Both the studio
+ * registry (`src/studio/capabilities/`, the credit-metered superset caller) and the edit-mode
+ * registry (`src/core/edit/capabilities/`, the lean preview caller) build on it. It supersedes
+ * the previously duplicated `studio/capabilities/errors.js` + `core/edit/capabilities/errors.ts`.
+ *
+ * One base class so callers — today the UI, tomorrow the agent loop — branch on `err.code`
+ * instead of string-matching messages. Every error carries the offending capability name when
+ * known, so failures are traceable without a stack dive.
+ */
+export type CapabilityErrorCode = 'CAPABILITY_ERROR' | 'VALIDATION' | 'UNAVAILABLE' | 'PRECHECK_FAILED' | 'NOT_IMPLEMENTED' | 'INSUFFICIENT_CREDITS' | 'UNKNOWN_CAPABILITY';
+export interface SchemaIssue {
+    path: string;
+    message: string;
+}
+export declare class CapabilityError extends Error {
+    code: CapabilityErrorCode;
+    capability: string | null;
+    cause?: unknown;
+    constructor(message: string, { code, capability, cause }?: {
+        code?: CapabilityErrorCode;
+        capability?: string | null;
+        cause?: unknown;
+    });
+}
+/** Input args failed the capability's inputSchema. Thrown before any write. */
+export declare class ValidationError extends CapabilityError {
+    issues: SchemaIssue[];
+    constructor(message: string, { capability, issues }?: {
+        capability?: string | null;
+        issues?: SchemaIssue[];
+    });
+}
+/** Capability is declared but not invokable yet (status: 'planned' / available()===false). */
+export declare class UnavailableError extends CapabilityError {
+    reason: string | null;
+    constructor(message: string, { capability, reason }?: {
+        capability?: string | null;
+        reason?: string | null;
+    });
+}
+/**
+ * Capability's precheck rejected the args against live state (no-op target, missing element,
+ * guard condition). Thrown before pushHistory / any write.
+ */
+export declare class PrecheckError extends CapabilityError {
+    reason: string | null;
+    constructor(message: string, { capability, reason }?: {
+        capability?: string | null;
+        reason?: string | null;
+    });
+}
+/**
+ * Wired capability whose execute() is not implemented (generative stubs). Distinct from
+ * UnavailableError: "active but unfinished", reachable only if status was flipped to 'active'
+ * before the implementation landed.
+ */
+export declare class NotImplementedError extends CapabilityError {
+    constructor(capability: string, message?: string | null);
+}
+/**
+ * Reserved for the future generative path: the backend credit check failed (402-style).
+ * Declared now so the agent loop can catch it without a follow-up refactor.
+ */
+export declare class InsufficientCreditsError extends CapabilityError {
+    required: number | null;
+    available: number | null;
+    constructor(message: string, { capability, required, available }?: {
+        capability?: string | null;
+        required?: number | null;
+        available?: number | null;
+    });
+}
+export declare class UnknownCapabilityError extends CapabilityError {
+    constructor(name: string);
+}

package/dist/capabilities/errors.js

@@ -0,0 +1,87 @@
+/**
+ * Capability layer error taxonomy (shared machinery).
+ *
+ * This is the ONE generic capability machinery, app-agnostic and layer-neutral
+ * (`src/capabilities/` imports nothing app-level — see `.agents/decisions/`). Both the studio
+ * registry (`src/studio/capabilities/`, the credit-metered superset caller) and the edit-mode
+ * registry (`src/core/edit/capabilities/`, the lean preview caller) build on it. It supersedes
+ * the previously duplicated `studio/capabilities/errors.js` + `core/edit/capabilities/errors.ts`.
+ *
+ * One base class so callers — today the UI, tomorrow the agent loop — branch on `err.code`
+ * instead of string-matching messages. Every error carries the offending capability name when
+ * known, so failures are traceable without a stack dive.
+ */
+export class CapabilityError extends Error {
+    code;
+    capability;
+    cause;
+    constructor(message, { code = 'CAPABILITY_ERROR', capability = null, cause = null } = {}) {
+        super(message);
+        this.name = 'CapabilityError';
+        this.code = code;
+        this.capability = capability;
+        if (cause)
+            this.cause = cause;
+    }
+}
+/** Input args failed the capability's inputSchema. Thrown before any write. */
+export class ValidationError extends CapabilityError {
+    issues;
+    constructor(message, { capability = null, issues = [] } = {}) {
+        super(message, { code: 'VALIDATION', capability });
+        this.name = 'ValidationError';
+        this.issues = issues;
+    }
+}
+/** Capability is declared but not invokable yet (status: 'planned' / available()===false). */
+export class UnavailableError extends CapabilityError {
+    reason;
+    constructor(message, { capability = null, reason = null } = {}) {
+        super(message, { code: 'UNAVAILABLE', capability });
+        this.name = 'UnavailableError';
+        this.reason = reason;
+    }
+}
+/**
+ * Capability's precheck rejected the args against live state (no-op target, missing element,
+ * guard condition). Thrown before pushHistory / any write.
+ */
+export class PrecheckError extends CapabilityError {
+    reason;
+    constructor(message, { capability = null, reason = null } = {}) {
+        super(message, { code: 'PRECHECK_FAILED', capability });
+        this.name = 'PrecheckError';
+        this.reason = reason;
+    }
+}
+/**
+ * Wired capability whose execute() is not implemented (generative stubs). Distinct from
+ * UnavailableError: "active but unfinished", reachable only if status was flipped to 'active'
+ * before the implementation landed.
+ */
+export class NotImplementedError extends CapabilityError {
+    constructor(capability, message = null) {
+        super(message || `Capability "${capability}" is not implemented yet`, { code: 'NOT_IMPLEMENTED', capability });
+        this.name = 'NotImplementedError';
+    }
+}
+/**
+ * Reserved for the future generative path: the backend credit check failed (402-style).
+ * Declared now so the agent loop can catch it without a follow-up refactor.
+ */
+export class InsufficientCreditsError extends CapabilityError {
+    required;
+    available;
+    constructor(message, { capability = null, required = null, available = null } = {}) {
+        super(message, { code: 'INSUFFICIENT_CREDITS', capability });
+        this.name = 'InsufficientCreditsError';
+        this.required = required;
+        this.available = available;
+    }
+}
+export class UnknownCapabilityError extends CapabilityError {
+    constructor(name) {
+        super(`Unknown capability "${name}"`, { code: 'UNKNOWN_CAPABILITY', capability: name });
+        this.name = 'UnknownCapabilityError';
+    }
+}

package/dist/capabilities/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared capability machinery — app-agnostic, layer-neutral registry + validator +
+ * error taxonomy. Both `src/studio/capabilities/` and `src/core/edit/capabilities/` build their
+ * own registry instances and descriptors on top of this. Imports nothing app-level (see
+ * `.agents/decisions/`). This is the generic core of the AI-ready capability seam.
+ */
+export { createCapabilityRegistry, type CapabilityRegistry, type CapabilityDescriptor, type CapabilityInfo, type CapabilityKind, type CapabilityStatus, type Reactivity, type InvokeMeta, type InvokeMode, type PrecheckResult, type RegistryCtx, } from './registry.js';
+export { validate, assertValid, type JsonSchema, type JsonType } from './schema.js';
+export * from './errors.js';

package/dist/capabilities/index.js

@@ -0,0 +1,9 @@
+/**
+ * Shared capability machinery — app-agnostic, layer-neutral registry + validator +
+ * error taxonomy. Both `src/studio/capabilities/` and `src/core/edit/capabilities/` build their
+ * own registry instances and descriptors on top of this. Imports nothing app-level (see
+ * `.agents/decisions/`). This is the generic core of the AI-ready capability seam.
+ */
+export { createCapabilityRegistry, } from './registry.js';
+export { validate, assertValid } from './schema.js';
+export * from './errors.js';

package/dist/capabilities/registry.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Capability registry — the single, named, validated chokepoint for edits (shared machinery).
+ *
+ * The ONE registry both callers build on (supersedes the duplicated
+ * `studio/capabilities/registry.js` + `core/edit/capabilities/registry.ts`). It is the SUPERSET:
+ * the studio uses the full pipeline (precheck → reversible history → credit cost → generative),
+ * the edit-mode caller uses the lean subset (validation + named dispatch + the preview/commit
+ * `mode`) and simply leaves the extra features unset. App-agnostic: `src/capabilities/` imports
+ * nothing app-level (see `.agents/decisions/`); all state/functions arrive via the injected ctx.
+ *
+ * Today the UI calls invoke()/invokeSync() with source:'ui'; tomorrow the agent loop calls the
+ * SAME registry with source:'agent'. Every mutation flows through one pipeline so history,
+ * validation, and availability are enforced in exactly one place.
+ *
+ * invoke() pipeline:
+ *   1. resolve        unknown name -> UnknownCapabilityError
+ *   2. assertAvailable status:'planned' / available(ctx)===false -> UnavailableError (no writes)
+ *   3. validate       args vs inputSchema -> ValidationError (no writes)
+ *   4. precheck       PURE, no writes. Returns { ok, reason, willMutate }. !ok -> PrecheckError
+ *   5. commit         only now: if reversible && willMutate !== false -> ctx.pushHistory()
+ *   6. execute        the actual write
+ *
+ * `mode` is the edit-mode preview/commit distinction (ignored by studio capabilities):
+ *   'preview' → live side effect only, no host broadcast   'commit' → side effect + emit.
+ */
+import { type JsonSchema } from './schema.js';
+export type CapabilityKind = 'mutation' | 'query' | 'generative';
+export type Reactivity = 'live' | 'structural';
+export type CapabilityStatus = 'active' | 'planned';
+export type InvokeMode = 'preview' | 'commit';
+export interface InvokeMeta {
+    source: string;
+    mode: InvokeMode;
+}
+export interface PrecheckResult {
+    ok: boolean;
+    reason?: string | null;
+    /** false suppresses the no-op history snapshot at the commit boundary. */
+    willMutate?: boolean;
+}
+/**
+ * The optional history hook the registry calls at the commit boundary for reversible mutations.
+ * A caller's ctx may include it (the studio does) or not (edit-mode has no history). It is NOT a
+ * generic constraint — the ctx type is free-form per caller — the registry just reads pushHistory
+ * off it when present.
+ */
+export interface RegistryCtx {
+    pushHistory?: () => void;
+}
+export interface CapabilityDescriptor<Ctx = Record<string, unknown>, Args = Record<string, unknown>> {
+    name: string;
+    kind: CapabilityKind;
+    description?: string;
+    inputSchema?: JsonSchema;
+    status?: CapabilityStatus;
+    reversible?: boolean;
+    /** Cost class of applying the edit: 'live' (cheap in-place) vs 'structural' (rebuild). */
+    reactivity?: Reactivity;
+    available?: (ctx: Ctx) => boolean;
+    cost?: (args: Args, ctx: Ctx) => number;
+    precheck?: (args: Args, ctx: Ctx, meta: InvokeMeta) => PrecheckResult | Promise<PrecheckResult>;
+    execute: (args: Args, ctx: Ctx, meta: InvokeMeta) => unknown;
+}
+/** Public, function-free view of a capability — what the agent tool-catalog builder consumes. */
+export interface CapabilityInfo {
+    name: string;
+    kind: CapabilityKind;
+    status: CapabilityStatus;
+    description: string;
+    inputSchema: JsonSchema;
+    reversible: boolean;
+    reactivity: Reactivity | null;
+}
+interface NormalizedCapability<Ctx> {
+    name: string;
+    kind: CapabilityKind;
+    status: CapabilityStatus;
+    description: string;
+    inputSchema: JsonSchema;
+    reversible: boolean;
+    reactivity: Reactivity | null;
+    available: (ctx: Ctx) => boolean;
+    cost: (args: never, ctx: Ctx) => number;
+    precheck: (args: never, ctx: Ctx, meta: InvokeMeta) => PrecheckResult | Promise<PrecheckResult>;
+    execute: (args: never, ctx: Ctx, meta: InvokeMeta) => unknown;
+}
+export interface CapabilityRegistry<Ctx = Record<string, unknown>> {
+    register: (descriptor: CapabilityDescriptor<Ctx>) => NormalizedCapability<Ctx>;
+    registerAll: (descriptors: CapabilityDescriptor<Ctx>[]) => CapabilityRegistry<Ctx>;
+    has: (name: string) => boolean;
+    get: (name: string) => NormalizedCapability<Ctx> | null;
+    /** Public catalog view of one capability by name (null if unknown). */
+    describe: (name: string) => CapabilityInfo | null;
+    list: (opts?: {
+        includePlanned?: boolean;
+        kind?: CapabilityKind | null;
+    }) => CapabilityInfo[];
+    isAvailable: (name: string) => boolean;
+    cost: (name: string, args?: Record<string, unknown>) => number;
+    invoke: (name: string, args?: Record<string, unknown>, opts?: Partial<InvokeMeta>) => Promise<unknown>;
+    invokeSync: (name: string, args?: Record<string, unknown>, opts?: Partial<InvokeMeta>) => unknown;
+}
+export declare function createCapabilityRegistry<Ctx = Record<string, unknown>>({ ctx }?: {
+    ctx?: Ctx;
+}): CapabilityRegistry<Ctx>;
+export {};

package/dist/capabilities/registry.js

@@ -0,0 +1,215 @@
+/**
+ * Capability registry — the single, named, validated chokepoint for edits (shared machinery).
+ *
+ * The ONE registry both callers build on (supersedes the duplicated
+ * `studio/capabilities/registry.js` + `core/edit/capabilities/registry.ts`). It is the SUPERSET:
+ * the studio uses the full pipeline (precheck → reversible history → credit cost → generative),
+ * the edit-mode caller uses the lean subset (validation + named dispatch + the preview/commit
+ * `mode`) and simply leaves the extra features unset. App-agnostic: `src/capabilities/` imports
+ * nothing app-level (see `.agents/decisions/`); all state/functions arrive via the injected ctx.
+ *
+ * Today the UI calls invoke()/invokeSync() with source:'ui'; tomorrow the agent loop calls the
+ * SAME registry with source:'agent'. Every mutation flows through one pipeline so history,
+ * validation, and availability are enforced in exactly one place.
+ *
+ * invoke() pipeline:
+ *   1. resolve        unknown name -> UnknownCapabilityError
+ *   2. assertAvailable status:'planned' / available(ctx)===false -> UnavailableError (no writes)
+ *   3. validate       args vs inputSchema -> ValidationError (no writes)
+ *   4. precheck       PURE, no writes. Returns { ok, reason, willMutate }. !ok -> PrecheckError
+ *   5. commit         only now: if reversible && willMutate !== false -> ctx.pushHistory()
+ *   6. execute        the actual write
+ *
+ * `mode` is the edit-mode preview/commit distinction (ignored by studio capabilities):
+ *   'preview' → live side effect only, no host broadcast   'commit' → side effect + emit.
+ */
+import { PrecheckError, UnavailableError, UnknownCapabilityError, ValidationError, } from './errors.js';
+import { assertValid } from './schema.js';
+const VALID_KINDS = new Set(['mutation', 'query', 'generative']);
+// Fill descriptor defaults once at registration so invoke() stays branch-light.
+function normalize(descriptor) {
+    if (!descriptor || typeof descriptor !== 'object')
+        throw new Error('[capabilities] descriptor must be an object');
+    const { name, kind } = descriptor;
+    if (typeof name !== 'string' || !name)
+        throw new Error('[capabilities] descriptor.name is required');
+    if (!VALID_KINDS.has(kind)) {
+        throw new Error(`[capabilities] "${name}" has invalid kind "${kind}" (expected mutation|query|generative)`);
+    }
+    const status = descriptor.status ?? 'active';
+    if (status !== 'active' && status !== 'planned') {
+        throw new Error(`[capabilities] "${name}" has invalid status "${status}" (expected active|planned)`);
+    }
+    if (typeof descriptor.execute !== 'function')
+        throw new Error(`[capabilities] "${name}" must define an execute() function`);
+    return {
+        name,
+        kind,
+        status,
+        description: descriptor.description ?? '',
+        inputSchema: descriptor.inputSchema ?? { type: 'object' },
+        reversible: descriptor.reversible === true,
+        reactivity: descriptor.reactivity ?? null,
+        available: typeof descriptor.available === 'function' ? descriptor.available : () => status === 'active',
+        cost: (typeof descriptor.cost === 'function' ? descriptor.cost : () => 0),
+        precheck: (typeof descriptor.precheck === 'function' ? descriptor.precheck : () => ({ ok: true })),
+        execute: descriptor.execute,
+    };
+}
+export function createCapabilityRegistry({ ctx = {} } = {}) {
+    const caps = new Map();
+    function register(descriptor) {
+        const cap = normalize(descriptor);
+        if (caps.has(cap.name))
+            throw new Error(`[capabilities] "${cap.name}" is already registered`);
+        caps.set(cap.name, cap);
+        return cap;
+    }
+    const has = (name) => caps.has(name);
+    const get = (name) => caps.get(name) || null;
+    // Function-free catalog view of a capability — never leaks execute/precheck to catalog-only
+    // callers (the future tool-schema builder).
+    function info(cap) {
+        return {
+            name: cap.name,
+            kind: cap.kind,
+            status: cap.status,
+            description: cap.description,
+            inputSchema: cap.inputSchema,
+            reversible: cap.reversible,
+            reactivity: cap.reactivity,
+        };
+    }
+    function describe(name) {
+        const cap = get(name);
+        return cap ? info(cap) : null;
+    }
+    function list({ includePlanned = false, kind = null } = {}) {
+        const out = [];
+        for (const cap of caps.values()) {
+            if (!includePlanned && cap.status !== 'active')
+                continue;
+            if (kind && cap.kind !== kind)
+                continue;
+            out.push(info(cap));
+        }
+        return out;
+    }
+    function isAvailable(name) {
+        const cap = get(name);
+        if (!cap || cap.status !== 'active')
+            return false;
+        try {
+            return cap.available(ctx) !== false;
+        }
+        catch {
+            return false;
+        }
+    }
+    function cost(name, args = {}) {
+        const cap = get(name);
+        if (!cap)
+            return 0;
+        try {
+            return Number(cap.cost(args, ctx)) || 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    // Steps 1–3 (resolve → availability → validate): pure, no side effects. Shared by both paths.
+    function prepareInvocation(name, args, meta) {
+        const cap = get(name);
+        if (!cap)
+            throw new UnknownCapabilityError(name);
+        if (cap.status !== 'active') {
+            throw new UnavailableError(`Capability "${name}" is declared but not available yet`, { capability: name, reason: `status:${cap.status}` });
+        }
+        let availResult;
+        try {
+            availResult = cap.available(ctx);
+        }
+        catch (err) {
+            throw new UnavailableError(`Capability "${name}" availability check threw`, { capability: name, reason: err?.message || String(err) });
+        }
+        if (availResult === false) {
+            throw new UnavailableError(`Capability "${name}" is not currently available`, { capability: name, reason: 'available(ctx) returned false' });
+        }
+        assertValid(cap.inputSchema, args, name);
+        void meta;
+        return cap;
+    }
+    function wrapPrecheckError(name, err) {
+        if (err instanceof ValidationError || err instanceof PrecheckError)
+            return err;
+        return new PrecheckError(`Precheck for "${name}" threw: ${err?.message || err}`, { capability: name, reason: err?.message || String(err) });
+    }
+    function resolvePrecheck(name, pre) {
+        const r = pre || { ok: true };
+        if (r.ok === false) {
+            throw new PrecheckError(`Precheck for "${name}" rejected: ${r.reason || 'no reason given'}`, { capability: name, reason: r.reason ?? null });
+        }
+        return r;
+    }
+    // commit boundary — snapshot only a change that will actually mutate.
+    function commitHistory(cap, pre) {
+        const pushHistory = ctx?.pushHistory;
+        if (cap.reversible && pre.willMutate !== false && typeof pushHistory === 'function') {
+            pushHistory();
+        }
+    }
+    const fullMeta = (opts) => ({ source: opts?.source ?? 'ui', mode: opts?.mode ?? 'commit' });
+    // Async pipeline — supports async precheck/execute (the generative/agent path).
+    async function invoke(name, args = {}, opts) {
+        const meta = fullMeta(opts);
+        const cap = prepareInvocation(name, args, meta);
+        let pre;
+        try {
+            pre = resolvePrecheck(name, await cap.precheck(args, ctx, meta));
+        }
+        catch (err) {
+            throw wrapPrecheckError(name, err);
+        }
+        commitHistory(cap, pre);
+        return cap.execute(args, ctx, meta);
+    }
+    // Synchronous pipeline for UI mutation/query callers — preserves handler ordering (the write
+    // lands before the caller's following side effects). Rejects async precheck/execute.
+    function invokeSync(name, args = {}, opts) {
+        const meta = fullMeta(opts);
+        const cap = prepareInvocation(name, args, meta);
+        let preResult;
+        try {
+            preResult = cap.precheck(args, ctx, meta);
+        }
+        catch (err) {
+            throw wrapPrecheckError(name, err);
+        }
+        if (preResult && typeof preResult.then === 'function') {
+            throw new Error(`Capability "${name}" has an async precheck — use invoke()`);
+        }
+        const pre = resolvePrecheck(name, preResult);
+        commitHistory(cap, pre);
+        const result = cap.execute(args, ctx, meta);
+        if (result && typeof result.then === 'function') {
+            throw new Error(`Capability "${name}" execute() is async — use invoke() (e.g. generative)`);
+        }
+        return result;
+    }
+    const api = {
+        register,
+        registerAll(descriptors) {
+            descriptors.forEach(register);
+            return api;
+        },
+        has,
+        get,
+        describe,
+        list,
+        isAvailable,
+        cost,
+        invoke,
+        invokeSync,
+    };
+    return api;
+}

package/dist/capabilities/schema.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tiny JSON-Schema-subset validator (shared machinery, TypeScript).
+ *
+ * The ONE validator both registries use (supersedes the duplicated
+ * `studio/capabilities/schema.js` + `core/edit/capabilities/schema.ts`). Deliberately NOT a
+ * dependency (no zod/ajv) — the app is bundle-weight sensitive and the house style is
+ * lightweight guard clauses. Each capability carries an `inputSchema` literal in this subset;
+ * the SAME literal is what the future agent layer hands the model as a tool definition, so
+ * there is no second schema language to keep in sync.
+ *
+ * Supported keywords (a pragmatic subset of JSON Schema draft-07):
+ *   type        'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+ *               (or an array of those — value matches if it satisfies any)
+ *   properties  per-key subschemas (objects)
+ *   required    array of keys that must be present and not undefined (objects)
+ *   items       subschema applied to every array element
+ *   enum        value must be one of the listed values
+ *   const       value must deep-equal the given value
+ *   nullable    when true, null always passes regardless of type
+ *   minimum / maximum                 numbers
+ *   minLength / maxLength             strings
+ *   minItems / maxItems               arrays
+ *   pattern     string regex source (tested with RegExp)
+ *
+ * A schema with no `type` accepts any value (still honouring enum/const/properties if set).
+ * Unknown keywords are ignored — forward-compatible, never throws on shape it doesn't know.
+ */
+import { type SchemaIssue } from './errors.js';
+export type JsonType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+export interface JsonSchema {
+    type?: JsonType | JsonType[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    enum?: unknown[];
+    const?: unknown;
+    nullable?: boolean;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    pattern?: string;
+}
+/** Returns { ok, issues }. Never throws. */
+export declare function validate(schema: JsonSchema, value: unknown): {
+    ok: boolean;
+    issues: SchemaIssue[];
+};
+/** Throws ValidationError when invalid; returns the value otherwise. Used by the registry. */
+export declare function assertValid<T>(schema: JsonSchema, value: T, capability?: string | null): T;