sh3-core 0.11.2 → 0.11.4

package/dist/actions/bindings.d.ts

@@ -1,4 +1,13 @@
 import { type Platform } from './shortcuts';
-import type { Action } from './types';
+import type { Action, BindingSource } from './types';
 export type BindingOverrides = Record<string, string | null>;
 export declare function effectiveShortcut(action: Action, overrides: BindingOverrides, platform?: Platform): string | null;
+/**
+ * Like {@link effectiveShortcut}, but also reports the binding source so
+ * consumers (e.g., Help views) can distinguish "no shortcut assigned"
+ * from "user turned this off" — both of which yield a `null` shortcut.
+ */
+export declare function effectiveShortcutWithSource(action: Action, overrides: BindingOverrides, platform?: Platform): {
+    shortcut: string | null;
+    source: BindingSource;
+};

package/dist/actions/bindings.js

@@ -15,3 +15,19 @@ export function effectiveShortcut(action, overrides, platform = 'other') {
         return null;
     return resolveMod(action.defaultShortcut, platform);
 }
+/**
+ * Like {@link effectiveShortcut}, but also reports the binding source so
+ * consumers (e.g., Help views) can distinguish "no shortcut assigned"
+ * from "user turned this off" — both of which yield a `null` shortcut.
+ */
+export function effectiveShortcutWithSource(action, overrides, platform = 'other') {
+    if (action.id in overrides) {
+        const o = overrides[action.id];
+        if (o === null)
+            return { shortcut: null, source: 'disabled' };
+        return { shortcut: canonicalizeShortcut(o), source: 'user' };
+    }
+    if (!action.defaultShortcut)
+        return { shortcut: null, source: 'none' };
+    return { shortcut: resolveMod(action.defaultShortcut, platform), source: 'default' };
+}

package/dist/actions/bindings.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { effectiveShortcut } from './bindings';
+import { effectiveShortcut, effectiveShortcutWithSource } from './bindings';
 const mkAction = (overrides = {}) => (Object.assign({ id: 'shard.save', label: 'Save', scope: 'home', run: () => { } }, overrides));
 describe('effectiveShortcut', () => {
     it('returns defaultShortcut when no override', () => {
@@ -28,3 +28,25 @@ describe('effectiveShortcut', () => {
         expect(effectiveShortcut(a, { 'shard.save': 'Ctrl+K' }, 'mac')).toBe('Ctrl+K');
     });
 });
+describe('effectiveShortcutWithSource', () => {
+    it('returns default + "default" when no override and defaultShortcut present', () => {
+        const a = mkAction({ defaultShortcut: 'Mod+S' });
+        expect(effectiveShortcutWithSource(a, {}, 'other'))
+            .toEqual({ shortcut: 'Ctrl+S', source: 'default' });
+    });
+    it('returns canonicalized override + "user" when user rebound to a key', () => {
+        const a = mkAction({ defaultShortcut: 'Mod+S' });
+        expect(effectiveShortcutWithSource(a, { 'shard.save': 'Ctrl+K' }, 'other'))
+            .toEqual({ shortcut: 'Ctrl+K', source: 'user' });
+    });
+    it('returns null + "disabled" when user rebound to null', () => {
+        const a = mkAction({ defaultShortcut: 'Mod+S' });
+        expect(effectiveShortcutWithSource(a, { 'shard.save': null }, 'other'))
+            .toEqual({ shortcut: null, source: 'disabled' });
+    });
+    it('returns null + "none" when no default and no override', () => {
+        const a = mkAction();
+        expect(effectiveShortcutWithSource(a, {}, 'other'))
+            .toEqual({ shortcut: null, source: 'none' });
+    });
+});

package/dist/actions/contextMenuModel.js

@@ -3,44 +3,9 @@
  * dispatcher state, returns a tiered, deduplicated, shortcut-annotated
  * item list the Svelte component renders without further logic.
  */
-import { isScopeActive, TIER_ORDER, } from './dispatcher.svelte';
+import { TIER_ORDER } from './dispatcher.svelte';
 import { effectiveShortcut } from './bindings';
-function normalizeScope(scope) {
-    return Array.isArray(scope) ? scope : [scope];
-}
-function scopeToTier(scope) {
-    if (scope === 'home')
-        return 'home';
-    if (scope === 'app')
-        return 'app';
-    if (typeof scope === 'string' && scope.startsWith('view:'))
-        return 'view';
-    if (typeof scope === 'string' && scope.startsWith('focus:'))
-        return 'focus';
-    return 'element';
-}
-function innermostActiveTier(scope, state, owner) {
-    // Build a map of tier → active scopes for this action, then walk
-    // TIER_ORDER from innermost → outermost to find the first active tier.
-    const scopes = normalizeScope(scope);
-    const tierBuckets = {};
-    for (const s of scopes) {
-        const tier = scopeToTier(s);
-        if (!tierBuckets[tier])
-            tierBuckets[tier] = [];
-        tierBuckets[tier].push(s);
-    }
-    for (const tier of TIER_ORDER) {
-        const bucket = tierBuckets[tier];
-        if (!bucket)
-            continue;
-        for (const s of bucket) {
-            if (isScopeActive(s, state, owner))
-                return tier;
-        }
-    }
-    return null;
-}
+import { scopeToTier, innermostActiveScope } from './scope-helpers';
 export function buildContextMenuModel(entries, state) {
     var _a;
     const byTier = {
@@ -52,11 +17,11 @@ export function buildContextMenuModel(entries, state) {
             continue;
         if (seen.has(entry.action.id))
             continue;
-        const tier = innermostActiveTier(entry.action.scope, state, entry.ownerShardId);
-        if (!tier)
+        const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
+        if (!winning)
             continue;
         seen.add(entry.action.id);
-        byTier[tier].push({
+        byTier[scopeToTier(winning)].push({
             id: entry.action.id,
             label: entry.action.label,
             shortcut: effectiveShortcut(entry.action, state.bindings, state.platform),

package/dist/actions/dispatcher.svelte.js

@@ -5,6 +5,7 @@
  * state snapshots.
  */
 import { effectiveShortcut } from './bindings';
+import { scopeToTier, normalizeScope } from './scope-helpers';
 export const TIER_ORDER = ['element', 'focus', 'view', 'app', 'home'];
 export function isScopeActive(scope, state, ownerShardId) {
     if (scope === 'home') {
@@ -31,20 +32,6 @@ export function isScopeActive(scope, state, ownerShardId) {
     }
     return false;
 }
-function scopeToTier(scope) {
-    if (scope === 'home')
-        return 'home';
-    if (scope === 'app')
-        return 'app';
-    if (typeof scope === 'string' && scope.startsWith('view:'))
-        return 'view';
-    if (typeof scope === 'string' && scope.startsWith('focus:'))
-        return 'focus';
-    return 'element';
-}
-function normalizeScope(scope) {
-    return Array.isArray(scope) ? scope : [scope];
-}
 export function buildTierIndex(entries, state) {
     const idx = {
         element: new Map(),

package/dist/actions/listActive.d.ts

@@ -0,0 +1,4 @@
+import type { ActionEntry } from './registry';
+import { type DispatcherState } from './dispatcher.svelte';
+import type { ActiveActionDescriptor } from './types';
+export declare function listActiveFromEntries(entries: ActionEntry[], state: DispatcherState): ActiveActionDescriptor[];

package/dist/actions/listActive.js

@@ -0,0 +1,42 @@
+/*
+ * Pure read-side producer for `shell.actions.listActive()`.
+ *
+ * Given a snapshot of the action registry and the dispatcher state,
+ * return one `ActiveActionDescriptor` per currently-active action, in
+ * tier-innermost-first order (element > focus > view > app > home),
+ * with registration order preserved within a tier.
+ *
+ * The shell's live wrapper calls this with `listActions()` + `getLiveDispatcherState()`.
+ */
+import { TIER_ORDER, } from './dispatcher.svelte';
+import { effectiveShortcutWithSource } from './bindings';
+import { innermostActiveScope, scopeBadge, scopeToTier } from './scope-helpers';
+export function listActiveFromEntries(entries, state) {
+    const byTier = {
+        element: [], focus: [], view: [], app: [], home: [],
+    };
+    const seen = new Set();
+    for (const entry of entries) {
+        if (seen.has(entry.action.id))
+            continue;
+        const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
+        if (!winning)
+            continue;
+        seen.add(entry.action.id);
+        const { shortcut, source } = effectiveShortcutWithSource(entry.action, state.bindings, state.platform);
+        byTier[scopeToTier(winning)].push({
+            id: entry.action.id,
+            label: entry.action.label,
+            effectiveShortcut: shortcut,
+            bindingSource: source,
+            scope: winning,
+            scopeBadge: scopeBadge(winning),
+            group: entry.action.group,
+            icon: entry.action.icon,
+            ownerShardId: entry.ownerShardId,
+            paletteItem: entry.action.paletteItem !== false,
+            contextItem: entry.action.contextItem !== false,
+        });
+    }
+    return TIER_ORDER.flatMap((tier) => byTier[tier]);
+}

package/dist/actions/listActive.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/actions/listActive.test.js

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import { listActiveFromEntries } from './listActive';
+const mkEntry = (a, owner = 'shard.x') => ({
+    ownerShardId: owner,
+    action: Object.assign({ id: 'a', label: 'A', scope: 'home', run: () => { } }, a),
+});
+const mkState = (o = {}) => (Object.assign({ activeAppId: null, activeAppRequiredShards: new Set(), autostartShards: new Set(), mountedViewIds: new Set(), focusedViewId: null, selection: null, bindings: {}, platform: 'other' }, o));
+describe('listActiveFromEntries', () => {
+    it('omits actions whose scope is not active', () => {
+        const entries = [mkEntry({ id: 'p', scope: 'app' })];
+        expect(listActiveFromEntries(entries, mkState())).toEqual([]);
+    });
+    it('includes an active home action with default shortcut resolution', () => {
+        const entries = [mkEntry({
+                id: 'open', label: 'Open', scope: 'home', defaultShortcut: 'Mod+O',
+            })];
+        const out = listActiveFromEntries(entries, mkState({ platform: 'mac' }));
+        expect(out).toHaveLength(1);
+        expect(out[0]).toMatchObject({
+            id: 'open', label: 'Open',
+            effectiveShortcut: 'Meta+O', bindingSource: 'default',
+            scope: 'home', scopeBadge: null,
+        });
+    });
+    it('reports innermost tier for multi-scope action', () => {
+        const entries = [mkEntry({
+                id: 'm', scope: ['app', 'view:editor'],
+            }, '__sh3core__')];
+        const state = mkState({
+            activeAppId: 'a', autostartShards: new Set(['__sh3core__']),
+            mountedViewIds: new Set(['editor']),
+        });
+        const out = listActiveFromEntries(entries, state);
+        expect(out[0].scope).toBe('view:editor');
+        expect(out[0].scopeBadge).toBe('view:editor');
+    });
+    it('reports bindingSource=disabled when user null-rebound', () => {
+        const entries = [mkEntry({
+                id: 'x', scope: 'home', defaultShortcut: 'Mod+S',
+            })];
+        const state = mkState({ bindings: { x: null } });
+        const out = listActiveFromEntries(entries, state);
+        expect(out[0].effectiveShortcut).toBeNull();
+        expect(out[0].bindingSource).toBe('disabled');
+    });
+    it('reports bindingSource=none when no default and no override', () => {
+        const entries = [mkEntry({ id: 'x', scope: 'home' })];
+        const out = listActiveFromEntries(entries, mkState());
+        expect(out[0].effectiveShortcut).toBeNull();
+        expect(out[0].bindingSource).toBe('none');
+    });
+    it('carries paletteItem/contextItem defaults and overrides', () => {
+        const entries = [mkEntry({
+                id: 'a', scope: 'home', paletteItem: false,
+            })];
+        const out = listActiveFromEntries(entries, mkState());
+        expect(out[0].paletteItem).toBe(false);
+        expect(out[0].contextItem).toBe(true); // defaults to true
+    });
+    it('dedupes by action id', () => {
+        const entries = [
+            mkEntry({ id: 'dup', scope: 'home' }, 'shard.a'),
+            mkEntry({ id: 'dup', scope: 'home' }, 'shard.b'),
+        ];
+        const out = listActiveFromEntries(entries, mkState());
+        expect(out).toHaveLength(1);
+        expect(out[0].ownerShardId).toBe('shard.a');
+    });
+    it('orders innermost tier first, stable by registration inside a tier', () => {
+        // `app` and `view:editor` both activate under an active app with the
+        // owning shard autostart-registered and the view mounted.
+        const entries = [
+            mkEntry({ id: 'a1', scope: 'app', label: 'A1' }, '__sh3core__'),
+            mkEntry({ id: 'v1', scope: 'view:editor', label: 'V1' }, '__sh3core__'),
+            mkEntry({ id: 'a2', scope: 'app', label: 'A2' }, '__sh3core__'),
+        ];
+        const state = mkState({
+            activeAppId: 'a',
+            autostartShards: new Set(['__sh3core__']),
+            mountedViewIds: new Set(['editor']),
+        });
+        const out = listActiveFromEntries(entries, state);
+        // view tier first (innermost of the two), then app tier in reg order.
+        expect(out.map((d) => d.id)).toEqual(['v1', 'a1', 'a2']);
+    });
+});

package/dist/actions/paletteModel.js

@@ -1,22 +1,11 @@
-import { isScopeActive } from './dispatcher.svelte';
+/*
+ * Palette candidate builder — returns every active (paletteItem !== false)
+ * action, deduplicated, with shortcut and scope badge resolved. Uses
+ * innermost-first scope selection so the badge matches keyboard dispatch
+ * and context-menu tiering (audit: RFC #24).
+ */
 import { effectiveShortcut } from './bindings';
-function normalize(s) {
-    return Array.isArray(s) ? s : [s];
-}
-function anyScopeActive(scope, state, owner) {
-    for (const s of normalize(scope)) {
-        if (isScopeActive(s, state, owner))
-            return s;
-    }
-    return null;
-}
-function scopeBadge(scope) {
-    if (scope === 'home' || scope === 'app')
-        return null;
-    if (typeof scope === 'string')
-        return scope; // view:X / focus:X
-    return scope.element;
-}
+import { innermostActiveScope, scopeBadge } from './scope-helpers';
 export function buildPaletteCandidates(entries, state) {
     const out = [];
     const seen = new Set();
@@ -25,15 +14,15 @@ export function buildPaletteCandidates(entries, state) {
             continue;
         if (seen.has(entry.action.id))
             continue;
-        const active = anyScopeActive(entry.action.scope, state, entry.ownerShardId);
-        if (!active)
+        const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
+        if (!winning)
             continue;
         seen.add(entry.action.id);
         out.push({
             id: entry.action.id,
             label: entry.action.label,
             shortcut: effectiveShortcut(entry.action, state.bindings, state.platform),
-            scopeBadge: scopeBadge(active),
+            scopeBadge: scopeBadge(winning),
         });
     }
     return out;

package/dist/actions/paletteModel.test.js

@@ -30,4 +30,20 @@ describe('buildPaletteCandidates', () => {
         const out = buildPaletteCandidates(entries, state);
         expect(out).toHaveLength(1);
     });
+    it('reports the innermost active scope in scopeBadge for multi-tier actions', () => {
+        const entries = [
+            mkEntry({
+                id: 'm', label: 'M',
+                scope: ['app', 'view:editor'],
+            }, '__sh3core__'),
+        ];
+        const state = mkState({
+            activeAppId: 'a',
+            autostartShards: new Set(['__sh3core__']),
+            mountedViewIds: new Set(['editor']),
+        });
+        const out = buildPaletteCandidates(entries, state);
+        expect(out).toHaveLength(1);
+        expect(out[0].scopeBadge).toBe('view:editor');
+    });
 });

package/dist/actions/scope-helpers.d.ts

@@ -0,0 +1,11 @@
+import type { AtomicScope, ActionScope } from './types';
+import { type DispatcherState, type TierName } from './dispatcher.svelte';
+export declare function scopeToTier(scope: AtomicScope): TierName;
+export declare function normalizeScope(scope: ActionScope): AtomicScope[];
+export declare function scopeBadge(scope: AtomicScope): string | null;
+/**
+ * Walk TIER_ORDER innermost→outermost; return the first `AtomicScope` of
+ * the given action whose tier is currently active. Returns `null` if no
+ * scope is active.
+ */
+export declare function innermostActiveScope(scope: ActionScope, state: DispatcherState, ownerShardId: string): AtomicScope | null;

package/dist/actions/scope-helpers.js

@@ -0,0 +1,51 @@
+/*
+ * Pure scope/tier helpers shared by the dispatcher, context menu,
+ * palette, and listActive(). Keep this file side-effect free — it is
+ * imported by both reactive and non-reactive modules.
+ */
+import { isScopeActive, TIER_ORDER, } from './dispatcher.svelte';
+export function scopeToTier(scope) {
+    if (scope === 'home')
+        return 'home';
+    if (scope === 'app')
+        return 'app';
+    if (typeof scope === 'string' && scope.startsWith('view:'))
+        return 'view';
+    if (typeof scope === 'string' && scope.startsWith('focus:'))
+        return 'focus';
+    return 'element';
+}
+export function normalizeScope(scope) {
+    return Array.isArray(scope) ? scope : [scope];
+}
+export function scopeBadge(scope) {
+    if (scope === 'home' || scope === 'app')
+        return null;
+    if (typeof scope === 'string')
+        return scope;
+    return scope.element;
+}
+/**
+ * Walk TIER_ORDER innermost→outermost; return the first `AtomicScope` of
+ * the given action whose tier is currently active. Returns `null` if no
+ * scope is active.
+ */
+export function innermostActiveScope(scope, state, ownerShardId) {
+    var _a;
+    const scopes = normalizeScope(scope);
+    const buckets = {};
+    for (const s of scopes) {
+        const tier = scopeToTier(s);
+        ((_a = buckets[tier]) !== null && _a !== void 0 ? _a : (buckets[tier] = [])).push(s);
+    }
+    for (const tier of TIER_ORDER) {
+        const bucket = buckets[tier];
+        if (!bucket)
+            continue;
+        for (const s of bucket) {
+            if (isScopeActive(s, state, ownerShardId))
+                return s;
+        }
+    }
+    return null;
+}

package/dist/actions/scope-helpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/actions/scope-helpers.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { scopeToTier, normalizeScope, scopeBadge, innermostActiveScope, } from './scope-helpers';
+const mkState = (o = {}) => (Object.assign({ activeAppId: null, activeAppRequiredShards: new Set(), autostartShards: new Set(), mountedViewIds: new Set(), focusedViewId: null, selection: null, bindings: {}, platform: 'other' }, o));
+describe('scopeToTier', () => {
+    it('maps atoms to tier names', () => {
+        expect(scopeToTier('home')).toBe('home');
+        expect(scopeToTier('app')).toBe('app');
+        expect(scopeToTier('view:editor')).toBe('view');
+        expect(scopeToTier('focus:pane-1')).toBe('focus');
+        expect(scopeToTier({ element: 'row' })).toBe('element');
+    });
+});
+describe('normalizeScope', () => {
+    it('wraps single scope', () => {
+        expect(normalizeScope('home')).toEqual(['home']);
+    });
+    it('returns arrays as-is', () => {
+        expect(normalizeScope(['home', 'app'])).toEqual(['home', 'app']);
+    });
+});
+describe('scopeBadge', () => {
+    it('returns null for home/app', () => {
+        expect(scopeBadge('home')).toBeNull();
+        expect(scopeBadge('app')).toBeNull();
+    });
+    it('returns the full string for view/focus scopes', () => {
+        expect(scopeBadge('view:editor')).toBe('view:editor');
+        expect(scopeBadge('focus:pane-1')).toBe('focus:pane-1');
+    });
+    it('returns the element type for element scopes', () => {
+        expect(scopeBadge({ element: 'row' })).toBe('row');
+    });
+});
+describe('innermostActiveScope', () => {
+    it('returns null when no scope is active', () => {
+        expect(innermostActiveScope('app', mkState(), 'owner')).toBeNull();
+    });
+    it('picks the innermost active tier across a multi-scope action', () => {
+        const state = mkState({
+            activeAppId: 'a', autostartShards: new Set(['owner']),
+            mountedViewIds: new Set(['editor']),
+        });
+        const winner = innermostActiveScope(['app', 'view:editor'], state, 'owner');
+        expect(winner).toBe('view:editor');
+    });
+    it('falls back to outer tier when inner is inactive', () => {
+        const state = mkState({
+            activeAppId: 'a', autostartShards: new Set(['owner']),
+        });
+        const winner = innermostActiveScope(['app', 'view:editor'], state, 'owner');
+        expect(winner).toBe('app');
+    });
+    it('element scope beats view scope when both active', () => {
+        const state = mkState({
+            activeAppId: 'a', autostartShards: new Set(['owner']),
+            mountedViewIds: new Set(['editor']),
+            selection: { type: 'row', ref: {}, ownerShardId: 'owner' },
+        });
+        const winner = innermostActiveScope(['view:editor', { element: 'row' }], state, 'owner');
+        expect(winner).toEqual({ element: 'row' });
+    });
+});

package/dist/actions/shellActions.test.js

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from 'vitest';
 import { shell } from '../shellRuntime.svelte';
 import { __setBindingsZone } from './bindings-store';
 import { __resetDispatcherStateForTest, setActiveApp } from './state.svelte';
+import { registerAction, __resetActionsRegistryForTest } from './registry';
 describe('shell.actions facade', () => {
     beforeEach(() => {
         __setBindingsZone({ bindings: {} });
@@ -20,3 +21,52 @@ describe('shell.actions facade', () => {
         expect(now['shard.x.save']).toBeUndefined();
     });
 });
+describe('shell.actions.listActive', () => {
+    beforeEach(() => {
+        __resetActionsRegistryForTest();
+        __resetDispatcherStateForTest();
+    });
+    it('returns descriptors for currently-active registered actions', () => {
+        const dispose = registerAction({
+            id: 'home.hello', label: 'Hello', scope: 'home',
+            defaultShortcut: 'Mod+H', run: () => { },
+        }, 'shard.test');
+        const snap = shell.actions.listActive();
+        expect(snap.map((d) => d.id)).toContain('home.hello');
+        dispose();
+    });
+    it('snapshot is stable across calls (returns fresh array)', () => {
+        registerAction({
+            id: 'home.a', label: 'A', scope: 'home', run: () => { },
+        }, 'shard.test');
+        const a = shell.actions.listActive();
+        const b = shell.actions.listActive();
+        expect(a).not.toBe(b);
+        expect(a.map((d) => d.id)).toEqual(b.map((d) => d.id));
+    });
+});
+describe('shell.actions.onActiveChange', () => {
+    beforeEach(() => {
+        __resetActionsRegistryForTest();
+        __resetDispatcherStateForTest();
+    });
+    it('fires on dispatcher state change', () => {
+        let n = 0;
+        const off = shell.actions.onActiveChange(() => { n++; });
+        setActiveApp('a', new Set());
+        expect(n).toBe(1);
+        off();
+    });
+    it('fires when an action is registered or unregistered', () => {
+        let n = 0;
+        const off = shell.actions.onActiveChange(() => { n++; });
+        const dispose = registerAction({
+            id: 't', label: 'T', scope: 'home', run: () => { },
+        }, 'shard.test');
+        expect(n).toBeGreaterThanOrEqual(1);
+        const afterRegister = n;
+        dispose();
+        expect(n).toBeGreaterThan(afterRegister);
+        off();
+    });
+});

package/dist/actions/state.svelte.d.ts

@@ -1,4 +1,16 @@
 import type { DispatcherState } from './dispatcher.svelte';
+/**
+ * Subscribe to any change that could affect the set of currently-active
+ * actions or their resolved shortcuts (app/view/focus/selection/bindings
+ * transitions). Call sites outside this module (e.g., the shell
+ * assembling registry-change notifications) dispatch via
+ * {@link __notifyActiveChange}.
+ */
+export declare function onActiveChange(cb: () => void): () => void;
+/** Internal — fired by the shell runtime when the action registry mutates. */
+export declare function __notifyActiveChange(): void;
+/** Test-only alias for the internal notifier. */
+export declare const __notifyActiveChangeForTest: typeof __notifyActiveChange;
 export declare function setActiveApp(appId: string | null, requiredShards: Set<string>): void;
 export declare function setAutostartShards(shards: Set<string>): void;
 export declare function setMountedViewIds(ids: Set<string>): void;

package/dist/actions/state.svelte.js

@@ -18,15 +18,46 @@ let mountedViewIds = $state(new Set());
 let focusedViewId = $state(null);
 let userBindings = $state({});
 const platform = detectPlatform();
+const activeChangeListeners = new Set();
+function notifyActiveChange() {
+    for (const cb of activeChangeListeners) {
+        try {
+            cb();
+        }
+        catch (err) {
+            console.error('[sh3] onActiveChange listener threw', err);
+        }
+    }
+}
+/**
+ * Subscribe to any change that could affect the set of currently-active
+ * actions or their resolved shortcuts (app/view/focus/selection/bindings
+ * transitions). Call sites outside this module (e.g., the shell
+ * assembling registry-change notifications) dispatch via
+ * {@link __notifyActiveChange}.
+ */
+export function onActiveChange(cb) {
+    activeChangeListeners.add(cb);
+    return () => { activeChangeListeners.delete(cb); };
+}
+/** Internal — fired by the shell runtime when the action registry mutates. */
+export function __notifyActiveChange() {
+    notifyActiveChange();
+}
+/** Test-only alias for the internal notifier. */
+export const __notifyActiveChangeForTest = __notifyActiveChange;
 export function setActiveApp(appId, requiredShards) {
     activeAppId = appId;
     activeAppRequiredShards = new Set(requiredShards);
+    notifyActiveChange();
 }
 export function setAutostartShards(shards) {
     autostartShards = new Set(shards);
+    notifyActiveChange();
 }
 export function setMountedViewIds(ids) {
     mountedViewIds = new Set(ids);
+    notifyActiveChange();
 }
 /**
  * One-shot snapshot: walk the active layout tree and update
@@ -42,12 +73,15 @@ export function syncMountedViewIdsFromLayout() {
             ids.add(r.viewId);
     }
     mountedViewIds = ids;
+    notifyActiveChange();
 }
 export function setFocusedViewId(id) {
     focusedViewId = id;
+    notifyActiveChange();
 }
 export function setUserBindings(bindings) {
     userBindings = Object.assign({}, bindings);
+    notifyActiveChange();
 }
 export function getLiveDispatcherState() {
     return {
@@ -64,6 +98,7 @@ export function getLiveDispatcherState() {
 export function addAutostartShard(id) {
     if (!autostartShards.has(id)) {
         autostartShards = new Set([...autostartShards, id]);
+        notifyActiveChange();
     }
 }
 export function __resetDispatcherStateForTest() {
@@ -73,4 +108,5 @@ export function __resetDispatcherStateForTest() {
     mountedViewIds = new Set();
     focusedViewId = null;
     userBindings = {};
+    activeChangeListeners.clear();
 }

package/dist/actions/state.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { setActiveApp, setFocusedViewId, setMountedViewIds, setUserBindings, getLiveDispatcherState, __resetDispatcherStateForTest, } from './state.svelte';
+import { setActiveApp, setAutostartShards, setFocusedViewId, setMountedViewIds, setUserBindings, getLiveDispatcherState, onActiveChange, __notifyActiveChangeForTest, __resetDispatcherStateForTest, } from './state.svelte';
 import { __resetSelectionForTest, makeSelectionApi } from './selection.svelte';
 describe('live dispatcher state', () => {
     beforeEach(() => {
@@ -38,3 +38,28 @@ describe('live dispatcher state', () => {
         expect((_a = getLiveDispatcherState().selection) === null || _a === void 0 ? void 0 : _a.type).toBe('orb');
     });
 });
+describe('onActiveChange', () => {
+    beforeEach(() => {
+        __resetDispatcherStateForTest();
+        __resetSelectionForTest();
+    });
+    it('fires on every setter', () => {
+        let n = 0;
+        const off = onActiveChange(() => { n++; });
+        setActiveApp('a', new Set(['s']));
+        setAutostartShards(new Set(['s']));
+        setMountedViewIds(new Set(['v']));
+        setFocusedViewId('v');
+        setUserBindings({ foo: 'Ctrl+K' });
+        expect(n).toBe(5);
+        off();
+        setActiveApp(null, new Set());
+        expect(n).toBe(5);
+    });
+    it('fires on external notify (used for registry change)', () => {
+        let n = 0;
+        onActiveChange(() => { n++; });
+        __notifyActiveChangeForTest();
+        expect(n).toBe(1);
+    });
+});

package/dist/actions/types.d.ts

@@ -54,3 +54,44 @@ export interface ResolvedAction {
     ownerShardId: string;
     effectiveShortcut: string | null;
 }
+/**
+ * Where an action's effective shortcut came from:
+ * - `'default'`  — `defaultShortcut` resolved for the current platform
+ * - `'user'`     — the user supplied an explicit override
+ * - `'disabled'` — the user rebound to `null` to disable dispatch
+ * - `'none'`     — no default and no override
+ */
+export type BindingSource = 'default' | 'user' | 'disabled' | 'none';
+/**
+ * Read-only snapshot describing one action that is currently active.
+ * Produced by `shell.actions.listActive()`. One descriptor per action id,
+ * reporting the innermost active scope (same tier order as keyboard
+ * dispatch: element > focus > view > app > home).
+ */
+export interface ActiveActionDescriptor {
+    /** Stable action id as registered. */
+    id: string;
+    /** Human-readable label as registered. */
+    label: string;
+    /**
+     * Shortcut string as it would dispatch right now (platform-resolved,
+     * user-rebind applied). `null` when `bindingSource` is `'disabled'` or
+     * `'none'`.
+     */
+    effectiveShortcut: string | null;
+    /**
+     * Where the effective shortcut came from. Help UIs can distinguish
+     * user-disabled (render greyed) from no-shortcut (hide).
+     */
+    bindingSource: BindingSource;
+    /** The innermost active tier of the action's scope. */
+    scope: AtomicScope;
+    /** Display hint: `null` for home/app, else full string or element type. */
+    scopeBadge: string | null;
+    /** Carried through from the registered action. */
+    group?: string;
+    icon?: string;
+    ownerShardId: string;
+    paletteItem: boolean;
+    contextItem: boolean;
+}

package/dist/api.d.ts

@@ -2,6 +2,7 @@ export { shell } from './shellRuntime.svelte';
 export type { Shell } from './shellRuntime.svelte';
 export type { Shard, ShardManifest, SourceShard, SourceShardManifest, ShardContext, ViewDeclaration, ViewFactory, ViewHandle, MountContext, } from './shards/types';
 export type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry, SplitDirection, SizeMode, LayoutTree, FloatEntry, LayoutPreset, CanonicalPreset, TreeRootRef as SlotLocation, } from './layout/types';
+export type { ActiveActionDescriptor, BindingSource, AtomicScope, ActionScope, } from './actions/types';
 export type { FloatManager, FloatOptions } from './overlays/float';
 export type { ModalManager } from './overlays/modal';
 export type { PopupManager } from './overlays/popup';
@@ -24,6 +25,8 @@ export type { SyncPolicy, SyncPolicyRule, DocStatus, ConflictFile, ConflictBranc
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';
 export type { ConflictItem, ConflictBranch as ConflictManagerBranch, ResolveOptions as ConflictResolveOptions, ResolveOutcome as ConflictResolveOutcome, ResolveDocumentsInput as ConflictResolveDocumentsInput, DocsResolveOutcome as ConflictDocsResolveOutcome, ConflictRenderer, ConflictRendererProps, ConflictsApi, } from './conflicts/api';
 export { CONFLICT_RENDERER_POINT, ConflictPermissionError, ConflictSessionOrphanedError, } from './conflicts/api';
+export type { ColorPickOptions, ColorContribution, ColorApi, } from './color/api';
+export { COLOR_PICKER_POINT } from './color/api';
 export { registeredShards, activeShards } from './shards/activate.svelte';
 export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
@@ -47,3 +50,5 @@ export { listVerbs } from './shards/registry';
 export { VERSION } from './version';
 export declare const FRAMEWORK_SHARD_IDS: readonly string[];
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';
+export { default as Button } from './primitives/Button.svelte';
+export { provideIcons, getIconSprite, type ButtonVariant } from './primitives/icon-context';

package/dist/api.js

@@ -32,6 +32,7 @@ export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focu
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';
 export { CONFLICT_RENDERER_POINT, ConflictPermissionError, ConflictSessionOrphanedError, } from './conflicts/api';
+export { COLOR_PICKER_POINT } from './color/api';
 // Shard introspection — read-only reactive maps exposing which shards are
 // known to the host and which are currently active. Intended for diagnostic
 // and tooling shards that need to visualize framework state. Phase 9
@@ -65,3 +66,8 @@ export const FRAMEWORK_SHARD_IDS = [
 ];
 // Theme token override API (shell-level theming support).
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';
+// UI primitives for shards and apps. Must live on the public shim surface
+// (api.ts) — not just index.ts — so dynamically loaded bundles can resolve
+// `import { Button } from 'sh3-core'` against the runtime shim in loader.ts.
+export { default as Button } from './primitives/Button.svelte';
+export { provideIcons, getIconSprite } from './primitives/icon-context';

package/dist/assets/favicon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" data-svg-designer-scene-id="13a98ace">
+  <rect id="07433d30" x="2" y="2" width="20" height="20" rx="2" fill="#a15c67" stroke="#ff7373" stroke-width="0.5" opacity="1"/>
+  <text id="deb1fa9e" x="2.0101" y="16.2415" font-family="monospace" font-size="12" font-weight="bold" fill="#2b0f2b" opacity="0.8">SH3</text>
+  <text id="055bb24a" x="2.0709" y="15.3866" font-family="monospace" font-size="12" font-weight="bold" fill="#fae3b6" opacity="1">SH3</text>
+</svg>

package/dist/color/api.d.ts

@@ -0,0 +1,38 @@
+/** Contribution-point id for color pickers. */
+export declare const COLOR_PICKER_POINT = "sh3.color-picker";
+export interface ColorPickOptions {
+    /** Initial color as '#rrggbb'. If omitted, contributors choose a default. */
+    initial?: string;
+    /** Request alpha support. Ignored by contributors that don't support it. */
+    alpha?: boolean;
+    /** Anchor element for floating/positioned pickers. Native fallback ignores. */
+    anchor?: HTMLElement;
+    /** Display title (e.g. 'Background color'). Native fallback ignores. */
+    title?: string;
+}
+/**
+ * A color-picker contribution. Higher `priority` wins; the inlined native
+ * fallback is priority 0, so contributors typically use >= 10.
+ *
+ * `open(opts)` resolves with '#rrggbb' (or '#rrggbbaa' when the contributor
+ * honors `opts.alpha`) or `null` if the user dismissed.
+ */
+export interface ColorContribution {
+    id: string;
+    priority?: number;
+    open(opts: ColorPickOptions): Promise<string | null>;
+}
+/** Shell-level color API, mounted at `shell.color`. */
+export interface ColorApi {
+    /**
+     * Open a color picker. Resolves with the chosen color as '#rrggbb'
+     * (or '#rrggbbaa' when a contributor honors `opts.alpha === true`),
+     * or `null` if the user dismissed.
+     *
+     * On browsers without `<input type="color">` cancel-event support, the
+     * returned promise may not resolve if the user closes the native
+     * fallback without committing. Install a color-picker shard (e.g.
+     * sh3-editor) to avoid this.
+     */
+    pick(opts?: ColorPickOptions): Promise<string | null>;
+}

package/dist/color/api.js

@@ -0,0 +1,10 @@
+/*
+ * Public types for the color-picker contribution point.
+ *
+ * A contribution registered at COLOR_PICKER_POINT is picked by the
+ * primitive in ./primitive.ts when `shell.color.pick()` is called.
+ * The native <input type="color"> fallback is inlined there at priority 0;
+ * contributed pickers typically register at priority >= 10.
+ */
+/** Contribution-point id for color pickers. */
+export const COLOR_PICKER_POINT = 'sh3.color-picker';

package/dist/color/native-fallback.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/color/native-fallback.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { register, __resetContributionsForTest } from '../contributions/registry';
+import { COLOR_PICKER_POINT } from './api';
+import { pickColor } from './primitive';
+describe('native fallback', () => {
+    beforeEach(() => __resetContributionsForTest());
+    afterEach(() => {
+        document.querySelectorAll('input[type="color"]').forEach((el) => el.remove());
+    });
+    it('creates an input[type=color], clicks it, and resolves on change', async () => {
+        const p = pickColor({ initial: '#ff8800' });
+        const el = document.querySelector('input[type="color"]');
+        expect(el).not.toBeNull();
+        expect(el.value).toBe('#ff8800');
+        el.value = '#112233';
+        el.dispatchEvent(new Event('change'));
+        await expect(p).resolves.toBe('#112233');
+        expect(document.querySelector('input[type="color"]')).toBeNull();
+    });
+    it('resolves null on cancel', async () => {
+        const p = pickColor();
+        const el = document.querySelector('input[type="color"]');
+        expect(el).not.toBeNull();
+        el.dispatchEvent(new Event('cancel'));
+        await expect(p).resolves.toBeNull();
+        expect(document.querySelector('input[type="color"]')).toBeNull();
+    });
+    it('ignores malformed initial values without crashing', () => {
+        pickColor({ initial: 'not-a-color' });
+        const el = document.querySelector('input[type="color"]');
+        expect(el).not.toBeNull();
+        expect(el.value).not.toBe('not-a-color');
+    });
+    it('priority-≥1 contributor bypasses native entirely', async () => {
+        register(COLOR_PICKER_POINT, {
+            id: 'c',
+            priority: 10,
+            open: () => Promise.resolve('#abcdef'),
+        });
+        await expect(pickColor()).resolves.toBe('#abcdef');
+        expect(document.querySelector('input[type="color"]')).toBeNull();
+    });
+});

package/dist/color/primitive.d.ts

@@ -0,0 +1,2 @@
+import { type ColorPickOptions } from './api';
+export declare function pickColor(opts?: ColorPickOptions): Promise<string | null>;

package/dist/color/primitive.js

@@ -0,0 +1,40 @@
+/*
+ * Color-picker selection primitive.
+ *
+ * Reads contributions registered at COLOR_PICKER_POINT, sorts by
+ * priority descending, and calls `open(opts)` on the winner. The
+ * inlined native fallback at priority 0 guarantees there is always
+ * at least one candidate.
+ */
+import { list } from '../contributions/registry';
+import { COLOR_PICKER_POINT } from './api';
+const nativeFallback = {
+    id: 'sh3.color-picker.native',
+    priority: 0,
+    open: ({ initial }) => new Promise((resolve) => {
+        const el = document.createElement('input');
+        el.type = 'color';
+        if (initial && /^#[0-9a-f]{6}$/i.test(initial))
+            el.value = initial;
+        let settled = false;
+        const settle = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            el.remove();
+            resolve(v);
+        };
+        el.addEventListener('change', () => settle(el.value));
+        el.addEventListener('cancel', () => settle(null));
+        el.style.position = 'fixed';
+        el.style.left = '-9999px';
+        document.body.appendChild(el);
+        el.click();
+    }),
+};
+export function pickColor(opts = {}) {
+    const contributed = list(COLOR_PICKER_POINT);
+    const winner = [...contributed, nativeFallback]
+        .sort((a, b) => { var _a, _b; return ((_a = b.priority) !== null && _a !== void 0 ? _a : 0) - ((_b = a.priority) !== null && _b !== void 0 ? _b : 0); })[0];
+    return winner.open(opts);
+}

package/dist/color/primitive.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/color/primitive.test.js

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { register, __resetContributionsForTest } from '../contributions/registry';
+import { COLOR_PICKER_POINT } from './api';
+import { pickColor } from './primitive';
+describe('pickColor / selection', () => {
+    beforeEach(() => __resetContributionsForTest());
+    it('picks the highest-priority contributor', async () => {
+        const low = {
+            id: 'low',
+            priority: 5,
+            open: vi.fn(() => Promise.resolve('#111111')),
+        };
+        const high = {
+            id: 'high',
+            priority: 50,
+            open: vi.fn(() => Promise.resolve('#222222')),
+        };
+        register(COLOR_PICKER_POINT, low);
+        register(COLOR_PICKER_POINT, high);
+        await expect(pickColor({ initial: '#ff0000' })).resolves.toBe('#222222');
+        expect(high.open).toHaveBeenCalledWith({ initial: '#ff0000' });
+        expect(low.open).not.toHaveBeenCalled();
+    });
+    it('passes opts through unchanged', async () => {
+        const open = vi.fn(() => Promise.resolve(null));
+        register(COLOR_PICKER_POINT, { id: 'c', priority: 10, open });
+        const opts = { initial: '#abcdef', alpha: true, title: 'Pick' };
+        await pickColor(opts);
+        expect(open).toHaveBeenCalledWith(opts);
+    });
+    it('re-reads contributions on each call (no caching)', async () => {
+        const first = vi.fn(() => Promise.resolve('#111111'));
+        const unreg = register(COLOR_PICKER_POINT, { id: 'a', priority: 10, open: first });
+        await pickColor();
+        unreg();
+        const second = vi.fn(() => Promise.resolve('#222222'));
+        register(COLOR_PICKER_POINT, { id: 'b', priority: 10, open: second });
+        await pickColor();
+        expect(first).toHaveBeenCalledTimes(1);
+        expect(second).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/color/shell-api.d.ts

@@ -0,0 +1,2 @@
+import type { ColorApi } from './api';
+export declare const colorApi: ColorApi;

package/dist/color/shell-api.js

@@ -0,0 +1,11 @@
+/*
+ * shell.color assembled API.
+ *
+ * The selector + inlined native fallback live in primitive.ts;
+ * this file just binds `pick` onto the object exposed on the shell
+ * singleton, mirroring conflicts/shell-api.ts.
+ */
+import { pickColor } from './primitive';
+export const colorApi = {
+    pick: pickColor,
+};

package/dist/index.d.ts

@@ -1,6 +1,4 @@
 export * from './api';
 export { default as Shell } from './Shell.svelte';
-export { default as Button } from './primitives/Button.svelte';
-export { provideIcons, getIconSprite, type ButtonVariant } from './primitives/icon-context';
 export type { ArtifactManifest } from './artifact';
 export * from './shell-shard/protocol';

package/dist/index.js

@@ -11,6 +11,4 @@
  */
 export * from './api';
 export { default as Shell } from './Shell.svelte';
-export { default as Button } from './primitives/Button.svelte';
-export { provideIcons, getIconSprite } from './primitives/icon-context';
 export * from './shell-shard/protocol';

package/dist/shellRuntime.svelte.d.ts

@@ -6,7 +6,9 @@ import { type ToastManager } from './overlays/toast';
 import { type FloatManager } from './overlays/float';
 import { type PresetManager } from './overlays/presets';
 import type { ConflictsApi } from './conflicts/api';
+import type { ColorApi } from './color/api';
 import { type OpenContextMenuOpts, type OpenPaletteOpts } from './actions/listeners';
+import type { ActiveActionDescriptor } from './actions/types';
 /**
  * The process-wide shell singleton exposed to shards and the shell's own
  * internal code. Provides state zone creation and overlay managers.
@@ -32,6 +34,8 @@ export interface Shell {
     presets: PresetManager;
     /** Conflict manager view. Shell-owned modal for conflict arbitration. */
     conflicts: ConflictsApi;
+    /** Color picker. Falls back to native <input type="color"> when no picker shard is contributed. */
+    color: ColorApi;
     /** Actions facade — rebind keys, query bindings, open menus/palette. */
     actions: ShellActionsApi;
 }
@@ -50,6 +54,22 @@ export interface ShellActionsApi {
     openContextMenu(opts: OpenContextMenuOpts): void;
     /** Open the command palette, optionally pre-filled. */
     openPalette(opts?: OpenPaletteOpts): void;
+    /**
+     * Snapshot of all currently-active actions with resolved shortcuts
+     * and badges. One descriptor per action id, in tier-innermost-first
+     * order. See {@link ActiveActionDescriptor}.
+     *
+     * Non-reactive: returns a fresh array on each call. Subscribe via
+     * {@link ShellActionsApi.onActiveChange} to re-call when the active
+     * set or shortcuts change.
+     */
+    listActive(): ActiveActionDescriptor[];
+    /**
+     * Subscribe to active-set changes: action registration/unregistration,
+     * active app / view / focus transitions, selection changes, user
+     * binding edits. Returns an unsubscribe function.
+     */
+    onActiveChange(cb: () => void): () => void;
 }
 /** The process-wide shell instance. Framework-internal code uses this directly; shards receive a scoped view via `ShardContext`. */
 export declare const shell: Shell;

package/dist/shellRuntime.svelte.js

@@ -21,9 +21,12 @@ import { toastManager } from './overlays/toast';
 import { floatManager } from './overlays/float';
 import { presetManager } from './overlays/presets';
 import { conflictsApi } from './conflicts/shell-api';
+import { colorApi } from './color/shell-api';
 import { loadUserBindings, saveUserBinding } from './actions/bindings-store';
 import { openContextMenu as listenersOpenContextMenu, openPalette as listenersOpenPalette, } from './actions/listeners';
-import { setUserBindings, getLiveDispatcherState } from './actions/state.svelte';
+import { setUserBindings, getLiveDispatcherState, onActiveChange as onActiveChangeState, __notifyActiveChange, } from './actions/state.svelte';
+import { listActions, onActionsChange } from './actions/registry';
+import { listActiveFromEntries } from './actions/listActive';
 const shellActions = {
     async rebind(appId, actionId, shortcut) {
         await saveUserBinding(appId, actionId, shortcut);
@@ -49,6 +52,17 @@ const shellActions = {
     },
     openContextMenu: listenersOpenContextMenu,
     openPalette: listenersOpenPalette,
+    listActive() {
+        return listActiveFromEntries(listActions(), getLiveDispatcherState());
+    },
+    onActiveChange(cb) {
+        const offState = onActiveChangeState(cb);
+        const offRegistry = onActionsChange(() => { __notifyActiveChange(); });
+        return () => {
+            offState();
+            offRegistry();
+        };
+    },
 };
 /** The process-wide shell instance. Framework-internal code uses this directly; shards receive a scoped view via `ShardContext`. */
 export const shell = {
@@ -59,5 +73,6 @@ export const shell = {
     float: floatManager,
     presets: presetManager,
     conflicts: conflictsApi,
+    color: colorApi,
     actions: shellActions,
 };

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.11.2";
+export declare const VERSION = "0.11.4";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.11.2';
+export const VERSION = '0.11.4';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "type": "module",
   "files": [
     "dist"