sh3-core 0.23.2 → 0.25.0

package/dist/BrandSlot.svelte

@@ -15,6 +15,15 @@
   import { getBreadcrumbAppId, getRegisteredApp } from './apps/registry.svelte';
   import { sessionState, switchProjectScope } from './projects/session-state.svelte';
   import { projectsState } from './projects-shard/projectsShard.svelte';
+  import { presetManager } from './overlays/presets';
+
+  function titleCasePresetName(name: string): string {
+    return name
+      .split(/[-_]/)
+      .filter((part) => part.length > 0)
+      .map((part) => part[0].toUpperCase() + part.slice(1))
+      .join(' ');
+  }
 
   const activeAppId = $derived(getLiveDispatcherState().activeAppId);
   const breadcrumbId = $derived(getBreadcrumbAppId());
@@ -30,15 +39,44 @@
     projectId ? projectsState.projects.find((p) => p.id === projectId)?.name ?? projectId : null,
   );
 
-  type Mode = 'brand' | 'app' | 'breadcrumb' | 'project-home' | 'project-app' | 'project-breadcrumb';
+  // Preset state is only meaningful while an app is attached. Existing
+  // BrandSlot tests set activeAppId without binding a preset blob, so the
+  // try/catch here is necessary, not just defensive.
+  const offDefault = $derived.by(() => {
+    if (activeAppId === null) return false;
+    try {
+      return presetManager.active() !== presetManager.default();
+    } catch {
+      return false;
+    }
+  });
+
+  const presetLabel = $derived.by(() => {
+    if (!offDefault) return null;
+    try {
+      return titleCasePresetName(presetManager.active());
+    } catch {
+      return null;
+    }
+  });
+
+  type Mode =
+    | 'brand'
+    | 'app'
+    | 'app-off-default'
+    | 'breadcrumb'
+    | 'project-home'
+    | 'project-app'
+    | 'project-app-off-default'
+    | 'project-breadcrumb';
 
   const mode: Mode = $derived.by(() => {
     if (projectId) {
-      if (activeAppId) return 'project-app';
+      if (activeAppId) return offDefault ? 'project-app-off-default' : 'project-app';
       if (breadcrumbId) return 'project-breadcrumb';
       return 'project-home';
     }
-    if (activeAppId) return 'app';
+    if (activeAppId) return offDefault ? 'app-off-default' : 'app';
     if (breadcrumbId) return 'breadcrumb';
     return 'brand';
   });
@@ -54,6 +92,14 @@
   function reenterProjectHome() {
     if (activeAppId) void returnToHome();
   }
+
+  function backToDefaultPreset() {
+    try {
+      presetManager.switchToDefault();
+    } catch {
+      // Blob unbound mid-click — nothing to do.
+    }
+  }
 </script>
 
 <div class="sh3-brand-slot">
@@ -61,6 +107,10 @@
     <span class="sh3-brand">SH3</span>
   {:else if mode === 'app'}
     <span class="sh3-brand sh3-brand-app">{activeLabel}</span>
+  {:else if mode === 'app-off-default'}
+    <button type="button" class="sh3-brand sh3-brand-app sh3-brand-clickable" onclick={backToDefaultPreset} title="Return to default layout">{activeLabel}</button>
+    <span class="sh3-brand-sep" aria-hidden="true">›</span>
+    <span class="sh3-brand-preset">{presetLabel}</span>
   {:else if mode === 'breadcrumb'}
     <span class="sh3-brand">SH3</span>
     <span class="sh3-brand-sep" aria-hidden="true">›</span>
@@ -73,6 +123,12 @@
     <span class="sh3-brand sh3-brand-project">{projectLabel}</span>
     <span class="sh3-brand-sep" aria-hidden="true">›</span>
     <span class="sh3-brand sh3-brand-app">{activeLabel}</span>
+  {:else if mode === 'project-app-off-default'}
+    <span class="sh3-brand sh3-brand-project">{projectLabel}</span>
+    <span class="sh3-brand-sep" aria-hidden="true">›</span>
+    <button type="button" class="sh3-brand sh3-brand-app sh3-brand-clickable" onclick={backToDefaultPreset} title="Return to default layout">{activeLabel}</button>
+    <span class="sh3-brand-sep" aria-hidden="true">›</span>
+    <span class="sh3-brand-preset">{presetLabel}</span>
   {:else if mode === 'project-breadcrumb'}
     <button type="button" class="sh3-brand sh3-brand-clickable" onclick={exitProject} title="Exit project">SH3</button>
     <span class="sh3-brand-sep" aria-hidden="true">›</span>
@@ -126,4 +182,7 @@
   .sh3-brand-clickable:hover {
     background: var(--sh3-bg-elevated);
   }
+  .sh3-brand-preset {
+    color: var(--sh3-fg-muted);
+  }
 </style>

package/dist/BrandSlot.test.js

@@ -11,6 +11,7 @@ import BrandSlot from './BrandSlot.svelte';
 import { setActiveApp, __resetDispatcherStateForTest } from './actions/state.svelte';
 import { registerApp, __resetAppRegistryForTest, __resetBreadcrumbForTest, breadcrumbApp, } from './apps/registry.svelte';
 import { launchApp } from './apps/lifecycle';
+import { __bindPresetBlobForTest, __resetPresetManagerForTest, } from './overlays/presets';
 let host;
 let cmp = null;
 function makeApp(id, label) {
@@ -27,6 +28,7 @@ beforeEach(() => {
     document.body.appendChild(host);
     __resetBreadcrumbForTest();
     __resetDispatcherStateForTest();
+    __resetPresetManagerForTest();
 });
 afterEach(() => {
     if (cmp) {
@@ -37,7 +39,20 @@ afterEach(() => {
     __resetAppRegistryForTest();
     __resetDispatcherStateForTest();
     vi.clearAllMocks();
+    __resetPresetManagerForTest();
 });
+function bindBlobWithPresets(activePreset, names, defaultHint) {
+    const blob = {
+        layoutVersion: 1,
+        activePreset,
+        presets: Object.fromEntries(names.map((n) => [
+            n,
+            { default: { docked: { type: 'slot', slotId: `${n}-s`, viewId: 'v' }, floats: [] } },
+        ])),
+    };
+    __bindPresetBlobForTest(blob, defaultHint);
+    return blob;
+}
 describe('BrandSlot', () => {
     it('renders SH3 when no app has launched this session', async () => {
         var _a;
@@ -68,4 +83,41 @@ describe('BrandSlot', () => {
         btn.click();
         expect(launchApp).toHaveBeenCalledWith('app.a');
     });
+    it('renders [App Name] (no preset chip) when active app is on default preset', async () => {
+        registerApp(makeApp('app.a', 'My App'));
+        breadcrumbApp.id = 'app.a';
+        setActiveApp('app.a', new Set());
+        bindBlobWithPresets('home', ['home', 'editing'], 'home');
+        cmp = mount(BrandSlot, { target: host, props: {} });
+        await tick();
+        expect(host.textContent).toContain('My App');
+        expect(host.textContent).not.toContain('Home');
+        expect(host.textContent).not.toContain('Editing');
+        // App segment is plain text (no button) in the default-preset case.
+        expect(host.querySelector('button')).toBeNull();
+    });
+    it('renders [App Name] › [Preset] with App clickable when off default', async () => {
+        registerApp(makeApp('app.a', 'My App'));
+        breadcrumbApp.id = 'app.a';
+        setActiveApp('app.a', new Set());
+        const blob = bindBlobWithPresets('editing', ['home', 'editing'], 'home');
+        cmp = mount(BrandSlot, { target: host, props: {} });
+        await tick();
+        expect(host.textContent).toMatch(/My App.*Editing/);
+        const btn = host.querySelector('button');
+        expect(btn).not.toBeNull();
+        expect(btn.textContent).toContain('My App');
+        btn.click();
+        await tick();
+        expect(blob.activePreset).toBe('home');
+    });
+    it('titlecases multi-word preset names with hyphens or underscores', async () => {
+        registerApp(makeApp('app.a', 'My App'));
+        breadcrumbApp.id = 'app.a';
+        setActiveApp('app.a', new Set());
+        bindBlobWithPresets('my-cool-preset', ['home', 'my-cool-preset'], 'home');
+        cmp = mount(BrandSlot, { target: host, props: {} });
+        await tick();
+        expect(host.textContent).toContain('My Cool Preset');
+    });
 });

package/dist/Sh3.svelte

@@ -79,19 +79,19 @@
 
     const edgePointers = new Set<number>();
 
-    function onPointerDown(e: PointerEvent): void {
+    const onPointerDown = (e: PointerEvent): void => {
       const rect = el.getBoundingClientRect();
       const local = e.clientX - rect.left;
       if (local >= EDGE_PX && local <= rect.width - EDGE_PX) return;
       const granted = claim(e.pointerId, { ownerId: 'sh3:edge', axis: 'x', priority: 'edge', depth: 0 });
       if (granted) edgePointers.add(e.pointerId);
-    }
+    };
 
-    function onPointerEnd(e: PointerEvent): void {
+    const onPointerEnd = (e: PointerEvent): void => {
       if (!edgePointers.has(e.pointerId)) return;
       revoke(e.pointerId, 'sh3:edge');
       edgePointers.delete(e.pointerId);
-    }
+    };
 
     el.addEventListener('pointerdown', onPointerDown);
     el.addEventListener('pointerup', onPointerEnd);

package/dist/actions/listActive.js

@@ -50,6 +50,7 @@ export function listActionsFromEntries(entries, state) {
             ownerShardId: entry.ownerShardId,
             paletteItem: entry.action.paletteItem !== false,
             contextItem: entry.action.contextItem !== false,
+            aiInvocable: entry.action.aiInvocable,
             submenu: entry.action.submenu,
             submenuOf: entry.action.submenuOf,
             active,

package/dist/actions/listActive.test.js

@@ -57,6 +57,19 @@ describe('listActiveFromEntries', () => {
         expect(out[0].paletteItem).toBe(false);
         expect(out[0].contextItem).toBe(true); // defaults to true
     });
+    it('propagates aiInvocable from the registered action, preserving undefined', () => {
+        const entries = [
+            mkEntry({ id: 'opt-out', scope: 'home', aiInvocable: false }),
+            mkEntry({ id: 'opt-in', scope: 'home', aiInvocable: true }),
+            mkEntry({ id: 'unset', scope: 'home' }),
+        ];
+        const out = listActiveFromEntries(entries, mkState());
+        const byId = Object.fromEntries(out.map((d) => [d.id, d]));
+        expect(byId['opt-out'].aiInvocable).toBe(false);
+        expect(byId['opt-in'].aiInvocable).toBe(true);
+        // `undefined` is significant — consumers filter `=== false`, not falsy.
+        expect(byId['unset'].aiInvocable).toBeUndefined();
+    });
     it('dedupes by action id', () => {
         const entries = [
             mkEntry({ id: 'dup', scope: 'home' }, 'shard.a'),

package/dist/actions/types.d.ts

@@ -14,6 +14,14 @@ export interface Action {
     scope: ActionScope;
     contextItem?: boolean;
     paletteItem?: boolean;
+    /**
+     * Opt-out flag for AI tool catalogs. Set `false` to hide this action
+     * from LLM-facing surfaces (e.g. `sh3-ai`'s action→tool adapter) — use
+     * for palette-only actions that need a UI picker and are meaningless
+     * to invoke programmatically. Defaults to `undefined` (catalog
+     * inclusion decided by the consumer).
+     */
+    aiInvocable?: boolean;
     /**
      * Optional menu container id. When set and the active app's declared
      * (or canonical fallback) menu list contains this id, the action
@@ -148,6 +156,8 @@ export interface ActiveActionDescriptor {
     ownerShardId: string;
     paletteItem: boolean;
     contextItem: boolean;
+    /** Carried through from the registered action; see `Action.aiInvocable`. */
+    aiInvocable?: boolean;
     /** True when this action is a submenu parent (children opened by drill). */
     submenu?: true;
     /** Parent action id when this action is a submenu child. */
@@ -187,6 +197,8 @@ export interface ActionDescriptor {
     ownerShardId: string;
     paletteItem: boolean;
     contextItem: boolean;
+    /** Carried through from the registered action; see `Action.aiInvocable`. */
+    aiInvocable?: boolean;
     /** True when this action is a submenu parent (children opened by drill). */
     submenu?: true;
     /** Parent action id when this action is a submenu child. */

package/dist/api.d.ts

@@ -65,6 +65,8 @@ export type { RunVerbOpts, RunVerbResult } from './runtime';
 export { registerShellMode } from './shell-shard/registerShellMode';
 export type { ShellModeDescriptor, ShellModeOutput, ShellModeDispatchHandler, ShellModeDispatchInput, ShellModeRunsOn, RichEntryHandle, StreamHandle, } from './shell-shard/contract';
 export { SHELL_MODE_CONTRIBUTION_POINT } from './shell-shard/contract';
+export { CONTEXT_SOURCE_POINT_ID } from './contributions/contextSource';
+export type { ContextSource } from './contributions/contextSource';
 export type { GestureRegistry, GestureHandle } from './gestures';
 export type { GestureType, Axis, ClaimPriority, ClaimEntry, PanEvent, ScrollEvent, ButtonEvent, PanOptions, DragOptions, ButtonOptions, ScrollOptions, } from './gestures/types';
 export { VERSION } from './version';

package/dist/api.js

@@ -65,6 +65,8 @@ export { runVerbProgrammatic } from './runtime';
 // Sh3 mode contributions (external shards extend the sh3 with new modes).
 export { registerShellMode } from './shell-shard/registerShellMode';
 export { SHELL_MODE_CONTRIBUTION_POINT } from './shell-shard/contract';
+// Context-source contributions (publishers register entries; consumers like sh3-ai pick them up).
+export { CONTEXT_SOURCE_POINT_ID } from './contributions/contextSource';
 // Package version.
 export { VERSION } from './version';
 // Framework shard IDs — shards that are always present (built-in to sh3-core).

package/dist/app/store/StoreView.svelte

@@ -8,7 +8,7 @@
 
   import { storeContext } from './storeShard.svelte';
   import { fetchArchive, buildPackageMeta } from '../../registry/client';
-  import { readFileFromArchive, readManifestFromArchive } from '../../registry/archive';
+  import { readFileFromArchive } from '../../registry/archive';
   import { installPackage } from '../../registry/installer';
   import { loadBundleModule, type LoadedBundle } from '../../registry/loader';
   import { extractBundlePermissions } from '../../registry/permission-descriptions';

package/dist/apps/types.d.ts

@@ -95,6 +95,14 @@ export interface AppManifest {
      * Optional default home-card color default to transparent if not set
      */
     color?: string;
+    /**
+     * Name of the preset (from `initialLayout: LayoutPreset[]`) that is treated
+     * as the entry/home preset. When set, clicking the app segment in the
+     * breadcrumb returns the user here; framework helpers also use it as the
+     * "back to default" target. When omitted, the first preset in declaration
+     * order is used. Ignored when `initialLayout` is not an array of presets.
+     */
+    defaultPreset?: string;
 }
 /**
  * Context object passed to `App.activate`. Provides app-scoped state zones

package/dist/chrome/MenuSheet.svelte

@@ -15,7 +15,6 @@
     resolveMenuContainers,
     resolveMenuItems,
     resolveSubmenuItems,
-    type MenuBarItem,
   } from '../actions/menuBarModel';
   import { listActions } from '../actions/registry';
   import { getLiveDispatcherState } from '../actions/state.svelte';
@@ -54,7 +53,16 @@
   }
 
   // --- derived items for current nav level ---------------------------
-  const currentItems = $derived.by(() => {
+  interface SheetItem {
+    id: string;
+    label: string;
+    isContainer: boolean;
+    isSubmenu: boolean;
+    shortcut: string | null;
+    disabled: boolean;
+  }
+
+  const currentItems = $derived.by<SheetItem[]>(() => {
     const entries = listActions();
     const nav = currentNav;
 
@@ -65,7 +73,10 @@
         .map((c) => ({
           id: c.id,
           label: c.label,
-          isContainer: true as const,
+          isContainer: true,
+          isSubmenu: false,
+          shortcut: null,
+          disabled: false,
         }));
     }
 
@@ -74,8 +85,9 @@
       return items.map((item) => ({
         id: item.id,
         label: item.label,
-        shortcut: item.shortcut,
+        isContainer: false,
         isSubmenu: item.submenu === true,
+        shortcut: item.shortcut,
         disabled: item.disabled,
       }));
     }
@@ -85,14 +97,15 @@
     return items.map((item) => ({
       id: item.id,
       label: item.label,
+      isContainer: false,
+      isSubmenu: item.submenu === true,
       shortcut: item.shortcut,
       disabled: item.disabled,
-      isSubmenu: item.submenu === true,
     }));
   });
 
   // --- actions --------------------------------------------------------
-  function handleTap(entry: { id: string; isContainer?: boolean; isSubmenu?: boolean }) {
+  function handleTap(entry: SheetItem) {
     if (entry.isContainer) {
       const c = containers.find((x) => x.id === entry.id);
       if (c) push({ kind: 'container', containerId: c.id, label: c.label });

package/dist/contributions/contextSource.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Contribution point id: shards register `ContextSource` descriptors here.
+ * Each registration adds one pickable entry in any consuming UI (e.g. the
+ * "SOURCES" section of the AI Edit modal when sh3-ai is installed) and may
+ * be picked up by future consumers. Lifecycle is publisher-owned — register
+ * when content becomes relevant (app activation, project load, selection),
+ * dispose when it stops being relevant.
+ */
+export declare const CONTEXT_SOURCE_POINT_ID = "sh3.contextSource";
+/** A single context-source contribution. */
+export interface ContextSource {
+    /**
+     * Globally unique. Convention: `<shardId>:<slug>`. Used as the picker
+     * selection key, so it must be stable across re-renders. Re-registering
+     * with an existing id silently replaces — generally dispose the prior
+     * registration first when swapping content.
+     */
+    id: string;
+    /** Short display name shown in the picker row and the chip body. */
+    label: string;
+    /**
+     * Tooltip in any consuming UI. Consumers may also surface this to
+     * downstream tools (e.g. as the description sh3-ai exposes when
+     * chat-side context tools land).
+     */
+    description?: string;
+    /**
+     * Drives prompt formatting (when consumed by sh3-ai) and the chip kind tag.
+     *  - `text` (default): value coerced to string, dumped raw.
+     *  - `markdown`: value coerced to string, wrapped in fenced ```markdown``` block.
+     *  - `json`: value `JSON.stringify`-ed with 2-space indent, wrapped in fenced ```json``` block.
+     */
+    kind?: 'text' | 'markdown' | 'json';
+    /**
+     * Sub-header under the picker's SOURCES section (e.g. the consuming
+     * shard's display name). Entries without a group fall under an "Other"
+     * sub-header.
+     */
+    group?: string;
+    /**
+     * Lazy fetcher. Called when the user picks the chip (for the expand
+     * preview pane) and again at consume time. May be sync or async.
+     * Returning null/undefined signals "no content available right now" —
+     * entry is silently omitted but the chip remains. Throwing/rejecting
+     * surfaces a toast and skips the entry.
+     */
+    get(): unknown | Promise<unknown>;
+}

package/dist/contributions/contextSource.js

@@ -0,0 +1,21 @@
+/*
+ * Public contract for context-source contributions. Shards register
+ * `ContextSource` descriptors at `CONTEXT_SOURCE_POINT_ID` via the
+ * standard `ctx.contributions.register` API; consumers (sh3-ai today,
+ * potentially inspectors / hover previews / chat-side context tools
+ * tomorrow) enumerate them via `ctx.contributions.list`.
+ *
+ * v1 has a single consumer (sh3-ai). The descriptor shape is hosted
+ * here so publisher shards do not need a devDependency on sh3-ai to
+ * contribute. Lifecycle is consumer-owned — see the JSDoc on
+ * `CONTEXT_SOURCE_POINT_ID` below.
+ */
+/**
+ * Contribution point id: shards register `ContextSource` descriptors here.
+ * Each registration adds one pickable entry in any consuming UI (e.g. the
+ * "SOURCES" section of the AI Edit modal when sh3-ai is installed) and may
+ * be picked up by future consumers. Lifecycle is publisher-owned — register
+ * when content becomes relevant (app activation, project load, selection),
+ * dispose when it stops being relevant.
+ */
+export const CONTEXT_SOURCE_POINT_ID = 'sh3.contextSource';

package/dist/documents/picker-primitive.d.ts

@@ -37,13 +37,4 @@ export interface DocumentPickerOptions {
      *  own namespace, so the user can't navigate into a dead-end root. */
     lockToShard?: boolean;
 }
-/**
- * Create a document picker API bound to a document listing function.
- * The listFn is derived from the shard's document zone + browse permission
- * and baked in at construction time so callers don't pass their own scope.
- *
- * When an `anchor` element is provided the browser opens as a popup
- * (anchored near the element). Without an anchor it opens as a centered
- * modal (the expected default for file-browser dialogs).
- */
 export declare function createDocumentPicker(listFn: DocListFn, options?: DocumentPickerOptions): DocumentPickerApi;

package/dist/documents/picker-primitive.js

@@ -2,15 +2,6 @@ import { sh3 } from '../sh3Runtime.svelte';
 import DocumentBrowser from '../primitives/widgets/_DocumentBrowser.svelte';
 const BOX_STYLE = 'max-width: min(800px, 95vw);';
 const MODAL_OPTS = { dismissOnBackdrop: true, boxStyle: BOX_STYLE };
-/**
- * Create a document picker API bound to a document listing function.
- * The listFn is derived from the shard's document zone + browse permission
- * and baked in at construction time so callers don't pass their own scope.
- *
- * When an `anchor` element is provided the browser opens as a popup
- * (anchored near the element). Without an anchor it opens as a centered
- * modal (the expected default for file-browser dialogs).
- */
 export function createDocumentPicker(listFn, options = {}) {
     const { listFolders, handle, readOnlyShard, initialShardId, lockToShard } = options;
     function openBrowser(browserProps, anchor) {

package/dist/layout/store.svelte.js

@@ -142,7 +142,7 @@ export function attachApp(app) {
     // their view factories. Binding the preset manager proxy happens here
     // so shards can read/switch presets from their activate() hook.
     appEntry = { appId: app.manifest.id, proxy, heldSlotIds: [] };
-    bindPresetBlob(proxy);
+    bindPresetBlob(proxy, app.manifest.defaultPreset);
     bindDrawerStoreToBlob(proxy);
 }
 /**

package/dist/overlays/presets.d.ts

@@ -6,16 +6,31 @@ export interface PresetManager {
     active(): string;
     /** Switch to the named preset. Throws if unknown. */
     switch(name: string): void;
+    /**
+     * Resolved default preset name. Returns the hint passed at bind time
+     * when it matches a known preset, otherwise the first preset in
+     * declaration order. Throws when no app is attached.
+     */
+    default(): string;
+    /**
+     * Switch to the resolved default. No-op when already on default.
+     * Throws when no app is attached.
+     */
+    switchToDefault(): void;
 }
 /**
  * Bind the manager to the attached app's `AppLayoutBlob` workspace-zone
  * proxy. Called from `attachApp` in the layout store.
+ *
+ * @param defaultPresetHint - Optional name from `AppManifest.defaultPreset`.
+ *   Used by `default()` / `switchToDefault()`. Falls back to first preset
+ *   when omitted or when the hint doesn't match any preset.
  */
-export declare function bindPresetBlob(blob: AppLayoutBlob): void;
+export declare function bindPresetBlob(blob: AppLayoutBlob, defaultPresetHint?: string): void;
 /** Unbind on detach. Called from `detachApp`. */
 export declare function unbindPresetBlob(): void;
 /** Test-only bind alias for tests that build a synthetic blob. */
-export declare function __bindPresetBlobForTest(blob: AppLayoutBlob): void;
+export declare function __bindPresetBlobForTest(blob: AppLayoutBlob, defaultPresetHint?: string): void;
 /** Test-only reset. Clears the binding. */
 export declare function __resetPresetManagerForTest(): void;
 export declare const presetManager: PresetManager;

package/dist/overlays/presets.js

@@ -18,24 +18,33 @@
  * all methods throw — there is no pre-boot fallback.
  */
 let boundBlob = null;
+let boundDefaultHint = null;
 /**
  * Bind the manager to the attached app's `AppLayoutBlob` workspace-zone
  * proxy. Called from `attachApp` in the layout store.
+ *
+ * @param defaultPresetHint - Optional name from `AppManifest.defaultPreset`.
+ *   Used by `default()` / `switchToDefault()`. Falls back to first preset
+ *   when omitted or when the hint doesn't match any preset.
  */
-export function bindPresetBlob(blob) {
+export function bindPresetBlob(blob, defaultPresetHint) {
     boundBlob = blob;
+    boundDefaultHint = defaultPresetHint !== null && defaultPresetHint !== void 0 ? defaultPresetHint : null;
 }
 /** Unbind on detach. Called from `detachApp`. */
 export function unbindPresetBlob() {
     boundBlob = null;
+    boundDefaultHint = null;
 }
 /** Test-only bind alias for tests that build a synthetic blob. */
-export function __bindPresetBlobForTest(blob) {
+export function __bindPresetBlobForTest(blob, defaultPresetHint) {
     boundBlob = blob;
+    boundDefaultHint = defaultPresetHint !== null && defaultPresetHint !== void 0 ? defaultPresetHint : null;
 }
 /** Test-only reset. Clears the binding. */
 export function __resetPresetManagerForTest() {
     boundBlob = null;
+    boundDefaultHint = null;
 }
 function requireBlob() {
     if (!boundBlob) {
@@ -56,8 +65,25 @@ function switchPreset(name) {
     }
     blob.activePreset = name;
 }
+function resolveDefault() {
+    const blob = requireBlob();
+    const keys = Object.keys(blob.presets);
+    if (boundDefaultHint && boundDefaultHint in blob.presets) {
+        return boundDefaultHint;
+    }
+    return keys[0];
+}
+function switchToDefault() {
+    const target = resolveDefault();
+    const blob = requireBlob();
+    if (blob.activePreset === target)
+        return;
+    blob.activePreset = target;
+}
 export const presetManager = {
     list: listPresets,
     active: activePreset,
     switch: switchPreset,
+    default: resolveDefault,
+    switchToDefault,
 };

package/dist/overlays/presets.test.js

@@ -37,4 +37,33 @@ describe('presetManager', () => {
     it('list() throws when no blob is bound', () => {
         expect(() => presetManager.list()).toThrow(/no app attached/);
     });
+    it('default() returns the explicit hint when it matches a known preset', () => {
+        __bindPresetBlobForTest(makeBlob('author', ['author', 'review', 'inspect']), 'review');
+        expect(presetManager.default()).toBe('review');
+    });
+    it('default() falls back to first preset when no hint is provided', () => {
+        __bindPresetBlobForTest(makeBlob('review', ['author', 'review']));
+        expect(presetManager.default()).toBe('author');
+    });
+    it('default() falls back to first preset when hint is unknown', () => {
+        __bindPresetBlobForTest(makeBlob('author', ['author', 'review']), 'nope');
+        expect(presetManager.default()).toBe('author');
+    });
+    it('default() throws when no blob is bound', () => {
+        expect(() => presetManager.default()).toThrow(/no app attached/);
+    });
+    it('switchToDefault() switches to the resolved default preset', () => {
+        const blob = makeBlob('review', ['author', 'review']);
+        __bindPresetBlobForTest(blob, 'author');
+        presetManager.switchToDefault();
+        expect(blob.activePreset).toBe('author');
+        expect(presetManager.active()).toBe('author');
+    });
+    it('switchToDefault() is a no-op when already on default', () => {
+        const blob = makeBlob('author', ['author', 'review']);
+        __bindPresetBlobForTest(blob, 'author');
+        const before = blob.activePreset;
+        presetManager.switchToDefault();
+        expect(blob.activePreset).toBe(before);
+    });
 });