@knowledge-medium/agent-cli 0.1.0

package/dist/kernel-types/src/extensions/exampleExtensions.d.ts

@@ -0,0 +1,19 @@
+import type { Block } from '../data/block';
+export interface ExampleExtensionDefinition {
+    /** Stable, kebab-case label used in commit history and source attribution. */
+    id: string;
+    /** Display name stored on the extension block. */
+    name: string;
+    /** Description stored on the extension block. */
+    description: string;
+    /** ESM module text. */
+    source: string;
+}
+export declare const exampleExtensions: readonly ExampleExtensionDefinition[];
+/**
+ * Append the example-extension blocks under `parentBlock`. Used by the
+ * `insert_example_extensions` command to re-seed examples in any
+ * workspace without rebuilding the user.
+ */
+export declare const insertExampleExtensionsUnder: (parentBlock: Block) => Promise<Block[]>;
+//# sourceMappingURL=exampleExtensions.d.ts.map

package/dist/kernel-types/src/extensions/exampleExtensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exampleExtensions.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/exampleExtensions.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAS1C,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAA;IACV,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAA;IACnB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAA;CACf;AAuVD,eAAO,MAAM,iBAAiB,EAAE,SAAS,0BAA0B,EA2ClE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,GACvC,aAAa,KAAK,KACjB,OAAO,CAAC,KAAK,EAAE,CAmBjB,CAAA"}

package/dist/kernel-types/src/extensions/extensionLoadErrors.d.ts

@@ -0,0 +1,28 @@
+import { ReactNode } from 'react';
+export type ExtensionLoadErrorsMap = ReadonlyMap<string, Error>;
+/**
+ * Plain non-React store for extension load errors. The React provider
+ * is a thin wrapper around this so the state machine itself is unit-
+ * testable without mounting a component tree.
+ */
+export declare class ExtensionLoadErrorStore {
+    private errors;
+    private readonly listeners;
+    getSnapshot: () => ExtensionLoadErrorsMap;
+    subscribe: (listener: () => void) => (() => void);
+    reportError: (blockId: string, error: Error) => void;
+    clearError: (blockId: string) => void;
+    reset: () => void;
+}
+export declare const ExtensionLoadErrorsProvider: ({ children, store, }: {
+    children: ReactNode;
+    store?: ExtensionLoadErrorStore;
+}) => import("react/jsx-runtime").JSX.Element;
+export declare const useExtensionLoadErrors: () => {
+    errors: ExtensionLoadErrorsMap;
+    reportError: (blockId: string, error: Error) => void;
+    clearError: (blockId: string) => void;
+    reset: () => void;
+};
+export declare const useExtensionLoadError: (blockId: string) => Error | undefined;
+//# sourceMappingURL=extensionLoadErrors.d.ts.map

package/dist/kernel-types/src/extensions/extensionLoadErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensionLoadErrors.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/extensionLoadErrors.tsx"],"names":[],"mappings":"AAAA,OAAO,EAEL,SAAS,EAIV,MAAM,OAAO,CAAA;AAGd,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AAE/D;;;;GAIG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6C;IAEvE,WAAW,QAAO,sBAAsB,CAAe;IAEvD,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAAgC;IAEhF,WAAW,GAAI,SAAS,MAAM,EAAE,OAAO,KAAK,KAAG,IAAI,CAKlD;IAED,UAAU,GAAI,SAAS,MAAM,KAAG,IAAI,CAMnC;IAED,KAAK,QAAO,IAAI,CAIf;CACF;AAYD,eAAO,MAAM,2BAA2B,GAAI,sBAGzC;IACD,QAAQ,EAAE,SAAS,CAAA;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAA;CAChC,4CASA,CAAA;AAKD,eAAO,MAAM,sBAAsB,QAAO;IACxC,MAAM,EAAE,sBAAsB,CAAA;IAC9B,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IACpD,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,KAAK,EAAE,MAAM,IAAI,CAAA;CAUlB,CAAA;AAED,eAAO,MAAM,qBAAqB,GAAI,SAAS,MAAM,KAAG,KAAK,GAAG,SAO/D,CAAA"}

package/dist/kernel-types/src/extensions/extensionLookup.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Find an installed extension block by id or by one of its labels.
+ *
+ * Direct SQL is the right primitive here: `repo.query.findExtensionBlocks`
+ * goes through the cached query layer, which doesn't reliably observe a
+ * freshly installed block when the kernel invalidation processors aren't
+ * active (e.g. in unit-test repos). enable / disable / uninstall happen
+ * immediately after install in the bridge flow, so the lookup needs to
+ * see the just-written row without waiting for cache invalidation.
+ */
+import type { BlockData } from '@/data/api';
+import type { Repo } from '@/data/repo';
+export interface ExtensionHandle {
+    /** Extension block id. Either `id` or `label` is required. */
+    id?: string;
+    /** Extension alias / extension:name (the label passed at install time). */
+    label?: string;
+}
+export interface ExtensionLookupResult {
+    block: BlockData;
+    /** Best human-readable label (first alias that isn't the block id). */
+    label: string | null;
+}
+export declare const findExtensionBlock: (repo: Repo, workspaceId: string, handle: ExtensionHandle) => Promise<ExtensionLookupResult | null>;
+//# sourceMappingURL=extensionLookup.d.ts.map

package/dist/kernel-types/src/extensions/extensionLookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensionLookup.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/extensionLookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,aAAa,CAAA;AAKrC,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,SAAS,CAAA;IAChB,uEAAuE;IACvE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAED,eAAO,MAAM,kBAAkB,GAC7B,MAAM,IAAI,EACV,aAAa,MAAM,EACnB,QAAQ,eAAe,KACtB,OAAO,CAAC,qBAAqB,GAAG,IAAI,CA0BtC,CAAA"}

package/dist/kernel-types/src/extensions/facet.d.ts

@@ -0,0 +1,84 @@
+export interface FacetResolveContext {
+    [key: string]: unknown;
+}
+export interface Facet<Input, Output = readonly Input[]> {
+    id: string;
+    combine: (values: readonly Input[], context: FacetResolveContext) => Output;
+    empty: (context: FacetResolveContext) => Output;
+    validate?: (value: unknown) => value is Input;
+    of: (value: Input, options?: FacetContributionOptions) => FacetContribution<Input>;
+}
+export interface FacetContributionOptions {
+    precedence?: number;
+    source?: string;
+    /** Dragged-along AppExtension subtree. Contributed iff the parent
+     *  contribution itself survives validation + any enclosing togglable
+     *  boundary. Use this when a sibling contribution exists *because of*
+     *  this one — e.g. an action that only makes sense when its renderer
+     *  contribution is also live, or a property-editor override that
+     *  only fires when its schema is registered. The resolver evaluates
+     *  parent-acceptance before recursing here, so an invalid or
+     *  filtered-out parent silently drops everything below. */
+    enables?: AppExtension;
+}
+export interface FacetContribution<Input> extends FacetContributionOptions {
+    type: 'facet-contribution';
+    facet: Pick<Facet<Input, unknown>, 'id' | 'validate'>;
+    value: Input;
+}
+export type AppExtension = FacetContribution<unknown> | readonly AppExtension[] | ((context: FacetResolveContext) => AppExtension | Promise<AppExtension>) | null | undefined | false;
+export type FacetFunction = (...args: never[]) => unknown;
+export declare const isFunction: <T extends FacetFunction>(value: unknown) => value is T;
+export type OptionalContributionResult<T> = T | null | undefined | false;
+export declare const resolveLastContributionResult: <Context, Result>(contributions: readonly ((context: Context) => OptionalContributionResult<Result>)[], context: Context, initialValue?: Result) => Result | undefined;
+export declare const combineLastContributionResult: <Context, Result>(getInitialValue?: (context: Context) => Result | undefined) => (contributions: readonly ((context: Context) => OptionalContributionResult<Result>)[]) => (context: Context) => Result | undefined;
+export declare function defineFacet<Input, Output = readonly Input[]>({ id, combine, empty, validate, }: {
+    id: string;
+    combine?: (values: readonly Input[], context: FacetResolveContext) => Output;
+    empty?: (context: FacetResolveContext) => Output;
+    validate?: (value: unknown) => value is Input;
+}): Facet<Input, Output>;
+/** Per-facet identifier for a runtime contribution bucket. Each
+ *  subscription owner manages its own bucket; setRuntimeContributions
+ *  replaces the bucket for that source id. Static contributions (from
+ *  the extension graph) keep the source string they were registered
+ *  with — they never share a bucket id with a runtime source. */
+export type RuntimeSourceId = string;
+type FacetChangeListener = () => void;
+export declare class FacetRuntime {
+    readonly context: FacetResolveContext;
+    private readonly staticContributionsByFacet;
+    private readonly runtimeContributionsByFacet;
+    private readonly cache;
+    private readonly facetListeners;
+    constructor(context: FacetResolveContext, contributions: readonly FacetContribution<unknown>[]);
+    private collectContributions;
+    read<Input, Output>(facet: Facet<Input, Output>): Output;
+    /** Replace the runtime contributions bucket for this facet under
+     *  `sourceId`. Empty `contributions` removes the bucket. Notifies
+     *  per-facet subscribers after the cache is invalidated. */
+    setRuntimeContributions<Input>(facet: Facet<Input, unknown>, sourceId: RuntimeSourceId, contributions: readonly Input[]): void;
+    /** Subscribe to changes for one facet. Fires after every
+     *  setRuntimeContributions call that targets this facet. Static
+     *  extension contributions don't fire this — they only change when
+     *  the whole runtime is rebuilt. */
+    onFacetChange(facetId: string, listener: FacetChangeListener): () => void;
+    private notifyFacetListeners;
+    contributions<Input>(facet: Facet<Input, unknown>): FacetContribution<Input>[];
+    /**
+     * Every facet id that has at least one contribution (static or
+     * runtime). Useful for introspection (agent bridge describeRuntime,
+     * debug pages).
+     */
+    facetIds(): string[];
+    /**
+     * Raw contributions for a facet, looked up by id rather than by
+     * facet object. Lets introspection callers enumerate without
+     * needing the original Facet definition in scope.
+     */
+    contributionsById(facetId: string): FacetContribution<unknown>[];
+}
+export declare function resolveFacetRuntime(extensions: AppExtension | readonly AppExtension[], context?: FacetResolveContext): Promise<FacetRuntime>;
+export declare function resolveFacetRuntimeSync(extensions: AppExtension | readonly AppExtension[], context?: FacetResolveContext): FacetRuntime;
+export {};
+//# sourceMappingURL=facet.d.ts.map

package/dist/kernel-types/src/extensions/facet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facet.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/facet.ts"],"names":[],"mappings":"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"}

package/dist/kernel-types/src/extensions/overridesCache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * First-paint cache for the runtime-toggle overrides map.
+ *
+ * `staticAppExtensions` resolves synchronously before PowerSync
+ * hydrates, so without a cache every system plugin's effect would
+ * start (and every mount would mount) only to be torn down ~one
+ * round-trip later when the synced Extensions block arrives. To
+ * avoid the flash, we mirror the synced overrides into a narrowly-
+ * scoped `ClientLocalSettings` entry per workspace, written from the
+ * extensions-settings meta-plugin's subscription effect, read by
+ * `AppRuntimeProvider` at boot.
+ *
+ * Schema is sparse: only entries that diverge from the handle's
+ * manifest default are recorded (matches `applyToggle` semantics).
+ * Absence means "use the manifest default" — so adding new plugins
+ * with `defaultEnabled: false` (opt-in / experimental) doesn't
+ * require migrating anyone's cached state.
+ */
+import { type ClientLocalSettings } from '@/utils/ClientLocalSettings.js';
+import type { Overrides } from '@/extensions/togglable.js';
+/** Plain-object form for JSON storage. Map<id, boolean> flattens to
+ *  `{[id]: boolean}`. */
+export type OverridesEncoded = Record<string, boolean>;
+export declare const encodeOverrides: (overrides: Overrides) => OverridesEncoded;
+export declare const decodeOverrides: (raw: unknown) => Overrides;
+/** Read the cached overrides for a workspace. Returns an empty map
+ *  if nothing is cached or the stored value is malformed (which
+ *  matches "use manifest defaults"). */
+export declare const readOverridesCache: (workspaceId: string, storage?: ClientLocalSettings) => Overrides;
+/** Write the overrides map for a workspace. Called from the
+ *  extensions-settings effect whenever the synced block changes. Writes
+ *  an empty object when the map has no entries (rather than removing
+ *  the key) so consumers can distinguish "hydrated, no overrides"
+ *  from "never hydrated, fall back to defaults" if they care. */
+export declare const writeOverridesCache: (workspaceId: string, overrides: Overrides, storage?: ClientLocalSettings) => void;
+//# sourceMappingURL=overridesCache.d.ts.map

package/dist/kernel-types/src/extensions/overridesCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overridesCache.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/overridesCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAsB,KAAK,mBAAmB,EAAC,MAAM,gCAAgC,CAAA;AAC5F,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,2BAA2B,CAAA;AAOxD;yBACyB;AACzB,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEtD,eAAO,MAAM,eAAe,GAAI,WAAW,SAAS,KAAG,gBAItD,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,KAAG,SAO9C,CAAA;AAED;;wCAEwC;AACxC,eAAO,MAAM,kBAAkB,GAC7B,aAAa,MAAM,EACnB,UAAS,mBAAyC,KACjD,SAGF,CAAA;AAED;;;;iEAIiE;AACjE,eAAO,MAAM,mBAAmB,GAC9B,aAAa,MAAM,EACnB,WAAW,SAAS,EACpB,UAAS,mBAAyC,KACjD,IAEF,CAAA"}

package/dist/kernel-types/src/extensions/pluginIds.d.ts

@@ -0,0 +1,20 @@
+/** Deterministic block id for a plugin-owned singleton block (e.g. a
+ *  "Library" root page that all imports live under).
+ *
+ *  Each plugin picks one stable namespace UUID *once* and hardcodes
+ *  it — re-deriving the same ids on subsequent runs is what makes
+ *  upserts idempotent across reinstalls and across the user's
+ *  devices. (`crypto.randomUUID()` in any browser console will give
+ *  you a fresh one.) Keys are arbitrary plugin-internal strings —
+ *  conventional choices: `'root'`, `'library-root'`, `'sync-state'`,
+ *  `'<external-record-id>'`. The workspace is mixed in so the same
+ *  plugin in two workspaces produces distinct ids.
+ *
+ *  Example:
+ *
+ *    const READWISE_NS = '0d4f1c2e-7e9a-4f4d-a4f1-2c0a3a6e7f01'
+ *    const rootId = pluginBlockId(workspaceId, READWISE_NS, 'library-root')
+ *    const bookId = pluginBlockId(workspaceId, READWISE_NS, `book:${userBookId}`)
+ */
+export declare const pluginBlockId: (workspaceId: string, pluginNamespace: string, key: string) => string;
+//# sourceMappingURL=pluginIds.d.ts.map

package/dist/kernel-types/src/extensions/pluginIds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginIds.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/pluginIds.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,aAAa,GACxB,aAAa,MAAM,EACnB,iBAAiB,MAAM,EACvB,KAAK,MAAM,KACV,MAA0D,CAAA"}

package/dist/kernel-types/src/extensions/resolveAppRuntime.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Boundary-aware FacetRuntime resolver.
+ *
+ * Wraps the existing facet collector pattern (see `facet.ts:259/287`)
+ * with two behaviours the bare collectors don't have:
+ *
+ *   1. `getBoundary(node)` on an array → look up `isEnabled(handle,
+ *      overrides)`; skip the whole subtree when the toggle resolves
+ *      to off. Essentials are forced on; non-essentials honour the
+ *      overrides map, falling back to `defaultEnabled ?? true`.
+ *
+ *   2. Recurse into `FacetContribution.enables` (a slice-7 field on
+ *      `FacetContributionOptions`) only when the parent contribution
+ *      itself passed validation — dragged-along extensions exist to
+ *      support their parent and are dropped when the parent is.
+ *
+ * Both behaviours apply identically across the sync and async walks
+ * (mirroring the facet.ts pair). The async walk additionally awaits
+ * function-valued AppExtensions; the sync walk throws on them, matching
+ * the existing `collectContributionsSync` policy.
+ *
+ * facet.ts has no awareness of `@/extensions/togglable.ts`; this module
+ * is the only place the two meet. Anyone calling `resolveFacetRuntime`
+ * directly still gets the bare behaviour — which is fine for the unit
+ * tests that don't care about toggle semantics. Production wiring goes
+ * through `resolveAppRuntime` / `resolveAppRuntimeSync` here.
+ */
+import { FacetRuntime, type AppExtension, type FacetResolveContext } from '@/extensions/facet.js';
+import { type Overrides } from '@/extensions/togglable.js';
+export interface ResolveAppRuntimeOptions {
+    overrides: Overrides;
+    context?: FacetResolveContext;
+    /** Safe mode — when true, every non-essential togglable boundary is
+     *  forced off regardless of the override map. Essentials still
+     *  resolve to on. This is the URL `?safeMode` recovery escape hatch:
+     *  even an explicit `true` override on a non-essential plugin is
+     *  ignored, because the goal is "get the app to a working state",
+     *  not "honour user preferences." */
+    safeMode?: boolean;
+}
+/** Build a FacetRuntime from an AppExtension tree, evaluating toggle
+ *  boundaries with the supplied overrides. Async — awaits any
+ *  function-valued nodes (e.g. `dynamicExtensionsExtension`). */
+export declare function resolveAppRuntime(extensions: AppExtension | readonly AppExtension[], options: ResolveAppRuntimeOptions): Promise<FacetRuntime>;
+/** Sync variant. Throws if a function-valued AppExtension is reached,
+ *  matching `collectContributionsSync` in facet.ts:300. The static
+ *  extension tree contains no functions today; `AppRuntimeProvider`
+ *  relies on that for first-paint resolution before React can await. */
+export declare function resolveAppRuntimeSync(extensions: AppExtension | readonly AppExtension[], options: ResolveAppRuntimeOptions): FacetRuntime;
+//# sourceMappingURL=resolveAppRuntime.d.ts.map

package/dist/kernel-types/src/extensions/resolveAppRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveAppRuntime.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/resolveAppRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,YAAY,EAEjB,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAA;AAElC,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,SAAS,CAAA;IACpB,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B;;;;;yCAKqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAiBD;;iEAEiE;AACjE,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,EAClD,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,YAAY,CAAC,CAOvB;AAED;;;wEAGwE;AACxE,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,EAClD,OAAO,EAAE,wBAAwB,GAChC,YAAY,CAOd"}

package/dist/kernel-types/src/extensions/runtimeActions.d.ts

@@ -0,0 +1,4 @@
+import { FacetRuntime } from '@/extensions/facet.js';
+import { ActionConfig } from '@/shortcuts/types.js';
+export declare const readRuntimeActions: (runtime: FacetRuntime) => readonly ActionConfig[];
+//# sourceMappingURL=runtimeActions.d.ts.map

package/dist/kernel-types/src/extensions/runtimeActions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeActions.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/runtimeActions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,eAAO,MAAM,kBAAkB,GAC7B,SAAS,YAAY,KACpB,SAAS,YAAY,EAAkC,CAAA"}

package/dist/kernel-types/src/extensions/runtimeContext.d.ts

@@ -0,0 +1,4 @@
+import { FacetRuntime } from '@/extensions/facet.js';
+export declare const AppRuntimeContextProvider: import("react").Context<FacetRuntime | undefined>;
+export declare function useAppRuntime(): FacetRuntime;
+//# sourceMappingURL=runtimeContext.d.ts.map

package/dist/kernel-types/src/extensions/runtimeContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeContext.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/runtimeContext.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAIpD,eAAO,MAAM,yBAAyB,mDAAoB,CAAA;AAE1D,wBAAgB,aAAa,IAAI,YAAY,CAM5C"}

package/dist/kernel-types/src/extensions/runtimeEvents.d.ts

@@ -0,0 +1,3 @@
+export declare const appRuntimeUpdateEvent = "app-runtime-update";
+export declare const refreshAppRuntime: () => void;
+//# sourceMappingURL=runtimeEvents.d.ts.map

package/dist/kernel-types/src/extensions/runtimeEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeEvents.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/runtimeEvents.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,uBAAuB,CAAA;AAEzD,eAAO,MAAM,iBAAiB,YAI7B,CAAA"}

package/dist/kernel-types/src/extensions/staticAppExtensions.d.ts

@@ -0,0 +1,6 @@
+import type { Repo } from '@/data/repo';
+import type { AppExtension } from '@/extensions/facet.js';
+export declare const staticAppExtensions: ({ repo }: {
+    repo: Repo;
+}) => AppExtension[];
+//# sourceMappingURL=staticAppExtensions.d.ts.map

package/dist/kernel-types/src/extensions/staticAppExtensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticAppExtensions.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/staticAppExtensions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AA4CvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,eAAO,MAAM,mBAAmB,GAAI,UAAQ;IAAC,IAAI,EAAE,IAAI,CAAA;CAAC,KAAG,YAAY,EAuEtE,CAAA"}

package/dist/kernel-types/src/extensions/staticDataExtensions.d.ts

@@ -0,0 +1,6 @@
+import type { AppExtension } from '@/extensions/facet.js';
+/** Static data facets that must be available before the React app runtime
+ *  resolves. Keep this list UI-free so repo bootstrap can install plugin
+ *  data ownership without importing component trees. */
+export declare const staticDataExtensions: AppExtension[];
+//# sourceMappingURL=staticDataExtensions.d.ts.map

package/dist/kernel-types/src/extensions/staticDataExtensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticDataExtensions.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/staticDataExtensions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAUzD;;wDAEwD;AACxD,eAAO,MAAM,oBAAoB,EAAE,YAAY,EAU9C,CAAA"}

package/dist/kernel-types/src/extensions/toastAppMount.d.ts

@@ -0,0 +1,4 @@
+import type { AppExtension } from './facet.ts';
+export declare const ToastAppMount: () => import("react/jsx-runtime").JSX.Element;
+export declare const toastAppMountExtension: AppExtension;
+//# sourceMappingURL=toastAppMount.d.ts.map

package/dist/kernel-types/src/extensions/toastAppMount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toastAppMount.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/toastAppMount.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,eAAO,MAAM,aAAa,+CAEzB,CAAA;AAED,eAAO,MAAM,sBAAsB,EAAE,YAUnC,CAAA"}

package/dist/kernel-types/src/extensions/togglable.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Togglable primitives — the runtime enable/disable surface.
+ *
+ * The shipping shapes match docs/plugin-runtime-toggle/design.ts. The
+ * design file is a typechecked sketch (`yarn tsc --noEmit -p
+ * docs/tsconfig.json`); this file is the real implementation. Anything
+ * that drifts between the two — field names, factory signatures,
+ * boundary semantics — is a correctness bug, not a stylistic one.
+ *
+ * Highlights:
+ *
+ *   - `Togglable` is the user-visible identity for a toggle. Its
+ *     `of(ext)` wraps an AppExtension array with a non-enumerable
+ *     BOUNDARY symbol carrying the handle, so the collector + discovery
+ *     walks can evaluate `isEnabled(handle, overrides)` without a side
+ *     registry of handles.
+ *
+ *   - Two factories, deliberately not one:
+ *       systemToggle({...})        — full surface
+ *       userExtensionToggle(block) — id locked to block.id,
+ *                                    defaultEnabled forced to false
+ *     The asymmetry is type-enforced: user extensions are loaded by
+ *     compiling a module, which we *skip* unless an override is `true`,
+ *     so display metadata must come from block properties that can be
+ *     read without compiling executable code.
+ */
+import type { AppExtension } from '@/extensions/facet.js';
+import type { BlockData } from '@/data/api';
+/** Where a togglable came from. The settings UI uses this to bucket
+ *  toggles into "Built-in extensions" vs "User extensions" sections, since
+ *  the two have different ergonomics (built-in extensions ship with the
+ *  app; user extensions can be added/removed/reloaded by the user).
+ *  Set by the factory and not user-settable. */
+export type TogglableKind = 'system' | 'user';
+export interface Togglable {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly essential?: boolean;
+    /** undefined ≡ true. Honoured for built-in extensions; forced false for
+     *  user extensions (see `userExtensionToggle`). */
+    readonly defaultEnabled?: boolean;
+    readonly kind: TogglableKind;
+    of(ext: AppExtension): AppExtension;
+}
+/** Read the boundary handle stored on an array, or undefined if the
+ *  node isn't a togglable boundary. */
+export declare function getBoundary(node: unknown): Togglable | undefined;
+/** Restore the boundary marker on an array produced by `.map()` or
+ *  similar (which always returns a fresh array, dropping non-enumerable
+ *  symbols). Used by `validateAndPrefix` so user-extension boundaries
+ *  survive normalisation. Exported as the canonical way to attach a
+ *  boundary to an existing array; do not redefine the symbol externally. */
+export declare function attachBoundary(target: AppExtension[], handle: Togglable): void;
+export interface SystemToggleOptions {
+    id: string;
+    name: string;
+    description?: string;
+    essential?: boolean;
+    defaultEnabled?: boolean;
+}
+export declare function systemToggle(opts: SystemToggleOptions): Togglable;
+/** Every label that identifies this extension block: the explicit
+ *  `extension:name` plus any aliases. The agent bridge uses this to
+ *  resolve `enable-extension <label>` / `uninstall-extension <label>`
+ *  to a block; the settings UI uses `blockOnlyName` (above) for
+ *  display. Same input, different projection. */
+export declare function extensionAliasValues(block: BlockData): string[];
+export declare function userExtensionToggle(block: BlockData): Togglable;
+/** Disabled-shell variant. Same factory: all metadata is block-local,
+ *  so no module compilation is needed. */
+export declare function userExtensionShellToggle(block: BlockData): Togglable;
+export type Overrides = ReadonlyMap<string, boolean>;
+export declare function isEnabled(handle: Togglable, overrides: Overrides): boolean;
+/** UI toggle convention. Returns a new overrides map; comparing
+ *  against `defaultEnabled ?? true` keeps the map free of entries that
+ *  match the manifest default. */
+export declare function applyToggle(overrides: Overrides, handle: Togglable, nextState: boolean): Overrides;
+//# sourceMappingURL=togglable.d.ts.map

package/dist/kernel-types/src/extensions/togglable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"togglable.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/togglable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,YAAY,CAAA;AAWzC;;;;gDAIgD;AAChD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE7C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B;uDACmD;IACnD,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,EAAE,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAAA;CACpC;AAeD;uCACuC;AACvC,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAGhE;AAED;;;;4EAI4E;AAC5E,wBAAgB,cAAc,CAC5B,MAAM,EAAE,YAAY,EAAE,EACtB,MAAM,EAAE,SAAS,GAChB,IAAI,CAMN;AAMD,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,SAAS,CAWjE;AA8BD;;;;iDAIiD;AACjD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAY/D;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,GACf,SAAS,CAWX;AAED;0CAC0C;AAC1C,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAEpE;AAMD,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEpD,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAK1E;AAED;;kCAEkC;AAClC,wBAAgB,WAAW,CACzB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,OAAO,GACjB,SAAS,CAMX"}

package/dist/kernel-types/src/extensions/useOverrides.d.ts

@@ -0,0 +1,36 @@
+/**
+ * React hook owning the runtime-toggle overrides map for a workspace.
+ *
+ * Combines two pieces that have to move together for the toggle
+ * pipeline to be correct:
+ *
+ *   1. **Sync read of the localStorage cache** at mount/render — so the
+ *      first paint sees the user's most recent intent without waiting
+ *      for PowerSync to hydrate the Extensions block.
+ *   2. **Subscribe to `appRuntimeUpdateEvent`** — when the meta-plugin's
+ *      subscription effect dispatches a refresh (cache diverged from
+ *      the synced block), bump local state so the memo invalidates and
+ *      re-reads the cache.
+ *
+ * The pair is one unit because they share an invariant: every
+ * `refreshAppRuntime()` dispatch is meaningful exactly because the
+ * caller has already updated the cache. Splitting them risks a memo
+ * that re-runs but doesn't re-read, or a re-read that doesn't take
+ * effect.
+ *
+ * Returns an empty map when `workspaceId` is null/undefined — that's
+ * the pre-workspace boot state and matches "no overrides, use manifest
+ * defaults".
+ */
+import type { Overrides } from '@/extensions/togglable.js';
+export interface UseOverridesResult {
+    overrides: Overrides;
+    /** Monotonic string updated on each `refreshAppRuntime()` dispatch.
+     *  Callers thread this into their resolver context so consumers can
+     *  see that the runtime has been rebuilt even when the override map
+     *  itself hasn't changed (e.g. extension content edits dispatch
+     *  refresh too). */
+    generation: string;
+}
+export declare const useOverrides: (workspaceId: string | undefined | null) => UseOverridesResult;
+//# sourceMappingURL=useOverrides.d.ts.map

package/dist/kernel-types/src/extensions/useOverrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOverrides.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/useOverrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,2BAA2B,CAAA;AAExD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,SAAS,CAAA;IACpB;;;;wBAIoB;IACpB,UAAU,EAAE,MAAM,CAAA;CACnB;AAID,eAAO,MAAM,YAAY,GACvB,aAAa,MAAM,GAAG,SAAS,GAAG,IAAI,KACrC,kBAsBF,CAAA"}

package/dist/kernel-types/src/extensions/useShortcutSurfaceActivations.d.ts

@@ -0,0 +1,22 @@
+import type { BlockInteractionContext, ShortcutSurface, ShortcutSurfaceContext } from '@/extensions/blockInteraction.js';
+import { Block } from '../data/block';
+type ShortcutSurfaceOptions = Partial<Omit<ShortcutSurfaceContext, keyof BlockInteractionContext | 'surface'>> & Record<string, unknown> & {
+    surfaceActive?: boolean;
+};
+/**
+ * Activate a shortcut surface for a block. Builds the full reactive
+ * context (block + repo + uiStateBlock + panel envelope + focus / edit
+ * mode / selection) from hooks and feeds it through the
+ * `shortcutSurfaceActivationsFacet` resolver. Contributions that gate
+ * on reactive state (e.g. vim normal mode opting out when the block is
+ * in edit mode) therefore re-evaluate when that state changes — which
+ * is what we want for shortcut surface scoping.
+ *
+ * Takes `block` directly rather than reading from a React context, so
+ * it doesn't subscribe to per-block state changes unrelated to
+ * shortcuts (and so resolver-side facets — layouts, decorators,
+ * surface props — keep stable identity through reactive updates).
+ */
+export declare function useShortcutSurfaceActivations(block: Block, surface: ShortcutSurface, options?: ShortcutSurfaceOptions): void;
+export {};
+//# sourceMappingURL=useShortcutSurfaceActivations.d.ts.map

package/dist/kernel-types/src/extensions/useShortcutSurfaceActivations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useShortcutSurfaceActivations.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/useShortcutSurfaceActivations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,eAAe,EACf,sBAAsB,EACvB,MAAM,kCAAkC,CAAA;AAGzC,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAarC,KAAK,sBAAsB,GACzB,OAAO,CAAC,IAAI,CAAC,sBAAsB,EAAE,MAAM,uBAAuB,GAAG,SAAS,CAAC,CAAC,GAChF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACxB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAIH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,sBAAoD,GAC5D,IAAI,CAyDN"}

package/dist/kernel-types/src/extensions/variantFacet.d.ts

@@ -0,0 +1,70 @@
+import { type Facet } from './facet.ts';
+/**
+ * A named alternative for a slot — something a user (or a programmatic
+ * gate) can pick between. Variants share a `Render` shape (a renderer,
+ * a layout, a configuration object…); the picker UI uses `id` + `label`.
+ */
+export interface Variant<Render> {
+    id: string;
+    label: string;
+    render: Render;
+}
+/**
+ * Per-variant contribution. Like other block-interaction contributions,
+ * returning `null`/`undefined`/`false` means "this variant does not
+ * apply for this context" — useful when a variant is only meaningful
+ * for some blocks (e.g. video-player layout only for video blocks).
+ */
+export type VariantContribution<Context, Render> = (context: Context) => Variant<Render> | null | undefined | false;
+/**
+ * What `runtime.read(variantFacet)` resolves to — a function from
+ * context to the registered set, plus convenience pickers. Selection
+ * itself is intentionally *not* baked into the facet: most useful
+ * selections (user prefs, per-block overrides) read reactive state and
+ * therefore need to happen in a React component, not inside the
+ * facet's cached `combine` step.
+ */
+export interface VariantSelection<Render> {
+    /** All variants that contributed for this context, in precedence
+     *  order (lowest precedence first — same order facet contributions
+     *  are visited generally). */
+    all: readonly Variant<Render>[];
+    /** Last variant in precedence order. Equivalent to the legacy
+     *  `combineLastContributionResult` semantics — the right pick for
+     *  facets where contributions self-gate by context. */
+    last: Variant<Render> | undefined;
+    /** First variant in precedence order. Useful as a fallback when no
+     *  user-driven selection has been made yet. */
+    first: Variant<Render> | undefined;
+    /** Look up a specific variant by id. Returns `undefined` if no
+     *  contribution registered that id (e.g. the user's saved
+     *  preference points at a removed plugin). */
+    byId: (id: string | null | undefined) => Variant<Render> | undefined;
+}
+export type VariantResolver<Context, Render> = (context: Context) => VariantSelection<Render>;
+/**
+ * Define a facet whose contributions register named alternatives
+ * (variants) for a slot. The resolved value enumerates the registered
+ * variants and offers convenience pickers (`last`, `first`, `byId`);
+ * the consumer decides which one to render — typically by reading a
+ * user preference reactively at render time.
+ *
+ * Why selection lives in the consumer: most useful selections want to
+ * react to a property/preference change (re-render when the user picks
+ * a different variant). The facet's `combine` runs once per facet read
+ * and is cached, so embedding selection here would either freeze the
+ * choice or force every reactive prop to be threaded through
+ * `BlockResolveContext` — defeating the resolver-context stability
+ * split (see `BlockResolveContext` doc).
+ */
+export declare function defineVariantFacet<Context, Render>({ id, }: {
+    id: string;
+}): Facet<VariantContribution<Context, Render>, VariantResolver<Context, Render>>;
+/**
+ * Construct a Variant in a single expression. Sugar for plugins that
+ * register a single variant inline (e.g. `defineVariant('flat',
+ * 'Flat', LinkedReferences)` reads more naturally than building the
+ * object literal). Functionally identical to `{id, label, render}`.
+ */
+export declare const defineVariant: <Render>(id: string, label: string, render: Render) => Variant<Render>;
+//# sourceMappingURL=variantFacet.d.ts.map

package/dist/kernel-types/src/extensions/variantFacet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variantFacet.d.ts","sourceRoot":"","sources":["../../../../../../src/extensions/variantFacet.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,KAAK,EACX,MAAM,YAAY,CAAA;AAEnB;;;;GAIG;AACH,MAAM,WAAW,OAAO,CAAC,MAAM;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,CAAC,OAAO,EAAE,MAAM,IAC7C,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAA;AAElE;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAAC,MAAM;IACtC;;kCAE8B;IAC9B,GAAG,EAAE,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,CAAA;IAC/B;;2DAEuD;IACvD,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IACjC;mDAC+C;IAC/C,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IAClC;;kDAE8C;IAC9C,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;CACrE;AAED,MAAM,MAAM,eAAe,CAAC,OAAO,EAAE,MAAM,IACzC,CAAC,OAAO,EAAE,OAAO,KAAK,gBAAgB,CAAC,MAAM,CAAC,CAAA;AAWhD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,EAClD,EAAE,GACH,EAAE;IACD,EAAE,EAAE,MAAM,CAAA;CACX,GAAG,KAAK,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAyBhF;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,EAClC,IAAI,MAAM,EACV,OAAO,MAAM,EACb,QAAQ,MAAM,KACb,OAAO,CAAC,MAAM,CAA4B,CAAA"}