sh3-core 0.17.0 → 0.19.0

package/dist/Sh3.svelte

@@ -26,6 +26,12 @@
   import { startServerSideStream } from './keys/revocation-bus.svelte';
   import BrandSlot from './BrandSlot.svelte';
   import MenuBar from './actions/MenuBar.svelte';
+  import CompactChrome from './chrome/CompactChrome.svelte';
+  import CompactRenderer from './layout/compact/CompactRenderer.svelte';
+  import { sh3 } from './sh3Runtime.svelte';
+  import { claim, revoke } from './gestures/pointerClaim';
+
+  let contentEl: HTMLElement | undefined = $state();
 
   const authenticated = $derived(isAuthenticated());
   const user = $derived(getUser());
@@ -34,6 +40,8 @@
   // getActiveApp() here: returnToHome() keeps the app warm (activeApp.id
   // stays set) and only flips the layout store's activeRoot back to 'home'.
   const onHome = $derived(getActiveRoot() === 'home');
+  // Reactive viewport class — drives the compact-vs-desktop chrome/body fork.
+  const viewportClass = $derived(sh3.viewport.current.class);
 
   // Keep the actions dispatcher's `mountedViewIds` set in sync with the
   // live layout tree, so `view:<viewId>` scope checks (context menu,
@@ -58,52 +66,99 @@
     const stop = startServerSideStream();
     return stop;
   });
+
+  // Register left/right edge zones as priority:'edge' pointer claims so that
+  // any shard with a priority:'normal' claim automatically beats the shell's
+  // edge-swipe gesture (carousel navigation, future side-panel reveals).
+  const EDGE_PX = 24;
+  $effect(() => {
+    const el = contentEl;
+    if (!el) return;
+
+    const edgePointers = new Set<number>();
+
+    function 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 {
+      if (!edgePointers.has(e.pointerId)) return;
+      revoke(e.pointerId, 'sh3:edge');
+      edgePointers.delete(e.pointerId);
+    }
+
+    el.addEventListener('pointerdown', onPointerDown);
+    el.addEventListener('pointerup', onPointerEnd);
+    el.addEventListener('pointercancel', onPointerEnd);
+
+    return () => {
+      el.removeEventListener('pointerdown', onPointerDown);
+      el.removeEventListener('pointerup', onPointerEnd);
+      el.removeEventListener('pointercancel', onPointerEnd);
+      for (const id of edgePointers) revoke(id, 'sh3:edge');
+      edgePointers.clear();
+    };
+  });
 </script>
 
-<div class="sh3">
-  <header class="sh3-tabbar" data-sh3-region="tabbar">
-    <button
-      type="button"
-      class="sh3-tabbar-home-button"
-      onclick={() => returnToHome()}
-      disabled={onHome}
-      title="Home"
-    >
-      <svg class="sh3-tabbar-home-icon" aria-hidden="true">
-        <use href="{iconsUrl}#house" />
-      </svg>
-    </button>
-    <BrandSlot />
-    <MenuBar />
-    {#if authenticated && user}
-      <div class="sh3-tabbar-user">
-        <span class="sh3-tabbar-user-name">{user.displayName}</span>
-        <span class="sh3-tabbar-tag">{elevated ? 'admin' : 'user'}</span>
-        {#if !isLocalOwner()}
-          <button
-            type="button"
-            class="sh3-tabbar-signout"
-            onclick={() => logout()}
-            title="Sign out"
-          >
-            <svg class="sh3-tabbar-signout-icon" aria-hidden="true">
-              <use href="{iconsUrl}#log-out" />
-            </svg>
-          </button>
-        {/if}
-      </div>
-    {/if}
-  </header>
+<div class="sh3" data-sh3-viewport={viewportClass}>
+  {#if viewportClass === 'desktop'}
+    <header class="sh3-tabbar" data-sh3-region="tabbar">
+      <button
+        type="button"
+        class="sh3-tabbar-home-button"
+        onclick={() => returnToHome()}
+        disabled={onHome}
+        title="Home"
+      >
+        <svg class="sh3-tabbar-home-icon" aria-hidden="true">
+          <use href="{iconsUrl}#house" />
+        </svg>
+      </button>
+      <BrandSlot />
+      <MenuBar />
+      {#if authenticated && user}
+        <div class="sh3-tabbar-user">
+          <span class="sh3-tabbar-user-name">{user.displayName}</span>
+          <span class="sh3-tabbar-tag">{elevated ? 'admin' : 'user'}</span>
+          {#if !isLocalOwner()}
+            <button
+              type="button"
+              class="sh3-tabbar-signout"
+              onclick={() => logout()}
+              title="Sign out"
+            >
+              <svg class="sh3-tabbar-signout-icon" aria-hidden="true">
+                <use href="{iconsUrl}#log-out" />
+              </svg>
+            </button>
+          {/if}
+        </div>
+      {/if}
+    </header>
+  {:else}
+    <CompactChrome />
+  {/if}
 
   <GuestBanner />
 
-  <main class="sh3-content" data-sh3-region="content" data-sh3-layer="0">
-    <LayoutRenderer />
+  <main class="sh3-content" data-sh3-region="content" data-sh3-layer="0" bind:this={contentEl}>
+    {#if viewportClass === 'desktop'}
+      <LayoutRenderer />
+    {:else}
+      <CompactRenderer />
+    {/if}
   </main>
 
-  <footer class="sh3-statusbar" data-sh3-region="statusbar">
-    <!-- alpha tag moved to Sh3Home title row -->
-  </footer>
+  {#if viewportClass === 'desktop'}
+    <footer class="sh3-statusbar" data-sh3-region="statusbar">
+      <!-- alpha tag moved to Sh3Home title row -->
+    </footer>
+  {/if}
 
   <OverlayRoots />
 
@@ -125,6 +180,19 @@
     position: relative;
     background: var(--sh3-grad-bg, var(--sh3-bg));
     color: var(--sh3-fg);
+    /* Edge-to-edge platforms (Tauri Android in particular) draw the
+     * webview under the system status / navigation bars. env() resolves
+     * to 0 elsewhere, so this is a no-op on desktop browsers and
+     * windowed Tauri builds. box-sizing on body/html is `content-box`
+     * by default, so padding here shrinks the grid area accordingly. */
+    box-sizing: border-box;
+    padding-top: env(safe-area-inset-top);
+    padding-bottom: env(safe-area-inset-bottom);
+    padding-left: env(safe-area-inset-left);
+    padding-right: env(safe-area-inset-right);
+  }
+  .sh3[data-sh3-viewport='compact'] {
+    grid-template-rows: var(--sh3-tabbar-height) auto 1fr;
   }
 
   .sh3-tabbar {

package/dist/actions/CommandPalette.svelte

@@ -35,9 +35,8 @@
   }
 </script>
 
-<!-- svelte-ignore a11y_autofocus -->
 <div class="sh3-palette" role="dialog" aria-label="Command palette" aria-modal="true" tabindex="-1" onkeydown={onKeydown}>
-  <input class="sh3-palette-input hell-base-input" bind:value={query} autofocus placeholder="Command…" />
+  <input class="sh3-palette-input hell-base-input" bind:value={query} placeholder="Command…" />
   <div class="sh3-palette-list" role="listbox">
     {#each ranked as item, i (item.id)}
       <button

package/dist/actions/listActionsFromEntries.test.js

@@ -75,4 +75,33 @@ describe('listActionsFromEntries', () => {
         expect(out).toHaveLength(1);
         expect(out[0].ownerShardId).toBe('shard.a');
     });
+    it('passes through submenu=true on a parent descriptor', () => {
+        const entries = [{
+                ownerShardId: 'shard.x',
+                action: { id: 'p', label: 'P', scope: 'home', submenu: true },
+            }];
+        const out = listActionsFromEntries(entries, mkState());
+        expect(out[0].submenu).toBe(true);
+        expect(out[0].submenuOf).toBeUndefined();
+    });
+    it('passes through submenuOf on a child descriptor', () => {
+        const entries = [
+            {
+                ownerShardId: 'shard.x',
+                action: {
+                    id: 'p:dark', label: 'Dark', scope: 'home',
+                    submenuOf: 'p', run: () => { },
+                },
+            },
+        ];
+        const out = listActionsFromEntries(entries, mkState());
+        expect(out[0].submenuOf).toBe('p');
+        expect(out[0].submenu).toBeUndefined();
+    });
+    it('omits submenu and submenuOf on plain actions', () => {
+        const entries = [mkEntry({ id: 'plain', scope: 'home' })];
+        const out = listActionsFromEntries(entries, mkState());
+        expect(out[0].submenu).toBeUndefined();
+        expect(out[0].submenuOf).toBeUndefined();
+    });
 });

package/dist/actions/listActive.js

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

package/dist/actions/listeners.js

@@ -94,6 +94,10 @@ export function dispatchActionProgrammatic(actionId, _opts) {
     const state = getLiveDispatcherState();
     const desc = listActionsFromEntries(entries, state).find((d) => d.id === actionId);
     if (!desc || !desc.active) {
+        if (entry.action.submenu === true &&
+            typeof entry.action.run !== 'function') {
+            return Promise.reject(new Error(`action "${actionId}" is a submenu parent — list children with listActions({ submenuOf: "${actionId}" })`));
+        }
         return Promise.reject(new Error(`action "${actionId}" is not active in current scope`));
     }
     // run is guaranteed non-null by `desc.active === true`.
@@ -345,7 +349,18 @@ export function openPalette(opts) {
             }
         },
         onClose: () => handle.close(),
-    }, { dismissOnBackdrop: true });
+    }, {
+        dismissOnBackdrop: true,
+        // On touch-only devices, autofocusing the palette input pops the
+        // on-screen keyboard before the user has expressed intent to type
+        // — the toolbar-button entry path expects to tap a result, not
+        // type. Discriminant: a touch-only device (no hover, coarse
+        // pointer) — desktop browsers and laptops with touchscreens
+        // still report `(any-hover: hover)`.
+        initialFocus: !(typeof window !== 'undefined'
+            && typeof window.matchMedia === 'function'
+            && window.matchMedia('(hover: none) and (pointer: coarse)').matches),
+    });
     if (previousFocus) {
         const innerClose = handle.close;
         handle.close = () => {

package/dist/actions/programmatic-dispatch.svelte.test.js

@@ -34,11 +34,18 @@ describe('dispatchActionProgrammatic', () => {
         await expect(dispatchActionProgrammatic('d')).rejects.toThrow(/action "d" is not active/);
         expect(run).not.toHaveBeenCalled();
     });
-    it('rejects on a submenu parent without run', async () => {
+    it('rejects on a submenu parent with the parent-specific message', async () => {
         registerAction({
             id: 's', label: 'S', scope: 'home', submenu: true,
         }, 'shard.x');
-        await expect(dispatchActionProgrammatic('s')).rejects.toThrow(/action "s" is not active/);
+        await expect(dispatchActionProgrammatic('s')).rejects.toThrow(/action "s" is a submenu parent — list children with listActions\(\{ submenuOf: "s" \}\)/);
+    });
+    it('still uses the generic inactive message for non-submenu inactive actions', async () => {
+        registerAction({
+            id: 'gated2', label: 'G', scope: 'app', run: () => { },
+        }, 'shard.x');
+        // No active app -> 'app' scope is inactive.
+        await expect(dispatchActionProgrammatic('gated2')).rejects.toThrow(/action "gated2" is not active/);
     });
     it('invokes run with invokedVia="programmatic" on happy path', async () => {
         let captured = null;

package/dist/actions/types.d.ts

@@ -148,6 +148,10 @@ export interface ActiveActionDescriptor {
     ownerShardId: string;
     paletteItem: boolean;
     contextItem: 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. */
+    submenuOf?: string;
 }
 /**
  * Read-only snapshot describing one action in the registry. Produced by
@@ -183,6 +187,10 @@ export interface ActionDescriptor {
     ownerShardId: string;
     paletteItem: boolean;
     contextItem: 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. */
+    submenuOf?: string;
     /** True when `runAction(id)` would dispatch right now. */
     active: boolean;
 }

package/dist/api.d.ts

@@ -1,5 +1,8 @@
 export { sh3 } from './sh3Runtime.svelte';
-export type { Sh3 } from './sh3Runtime.svelte';
+export type { Sh3, Sh3Drawers, Sh3Viewport } from './sh3Runtime.svelte';
+export type { ViewportClass, ViewportInfo } from './viewport/types';
+export type { SlotRole } from './layout/types';
+export type { DrawerAnchor, DrawerSpec, DrawerState, DrawerStateMap, CompactRendering, } from './layout/compact/types';
 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 { ActionDescriptor, ActiveActionDescriptor, BindingSource, AtomicScope, ActionScope, } from './actions/types';
@@ -16,6 +19,8 @@ export type { EnvState } from './env/types';
 export type { App, AppManifest, SourceApp, SourceAppManifest, AppContext, } from './apps/types';
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
+export type { LaunchAppOptions } from './apps/lifecycle';
+export type { FileRef, FileHandlerDescriptor, FileHandlerMatch, FileHandlerHeader, FileHandlerPattern, FileHandlerOpen, } from './files/types';
 export { pushNavEntry } from './navigation';
 export type { NavEntry, NavEntryHandle } from './navigation';
 export { spawnSatellite } from './sh3Api/window';
@@ -58,6 +63,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 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';
 export declare const FRAMEWORK_SHARD_IDS: readonly string[];
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/app/store/storeShard.svelte.js

@@ -26,27 +26,7 @@ import { extractBundlePermissions } from '../../registry/permission-descriptions
 import { serverInstallPackage, fetchServerPackages, serverUninstallPackage } from '../../env/client';
 import { VERSION } from '../../version';
 import { installVerb, uninstallVerb, appinfoVerb, updateVerb } from './verbs';
-/**
- * Compare two semver-like version strings.
- * Returns true only if `available` is strictly greater than `installed`.
- * Compares major.minor.patch left-to-right as integers.
- * Non-numeric segments are treated as 0.
- */
-function isNewerVersion(available, installed) {
-    var _a, _b;
-    const a = available.split('.').map((s) => parseInt(s, 10) || 0);
-    const b = installed.split('.').map((s) => parseInt(s, 10) || 0);
-    const len = Math.max(a.length, b.length);
-    for (let i = 0; i < len; i++) {
-        const av = (_a = a[i]) !== null && _a !== void 0 ? _a : 0;
-        const bv = (_b = b[i]) !== null && _b !== void 0 ? _b : 0;
-        if (av > bv)
-            return true;
-        if (av < bv)
-            return false;
-    }
-    return false;
-}
+import { isNewerVersion } from './version';
 /**
  * Pick a version entry from a resolved package. When `requested` is
  * undefined returns `latest`; when set, finds the matching entry by

package/dist/app/store/version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Compare two artifact version strings for the app store update check.
+ *
+ * Handles semver build-metadata suffixes (`+N`): per ADR-013 the build suffix
+ * represents artifact iterations of the same release, so `1.0.0+1 > 1.0.0`
+ * and `1.0.0+2 > 1.0.0+1`. A canonical release (no suffix) is not considered
+ * newer than a suffixed one.
+ *
+ * Returns true only when `available` is strictly greater than `installed`.
+ */
+export declare function isNewerVersion(available: string, installed: string): boolean;

package/dist/app/store/version.js

@@ -0,0 +1,39 @@
+/**
+ * Compare two artifact version strings for the app store update check.
+ *
+ * Handles semver build-metadata suffixes (`+N`): per ADR-013 the build suffix
+ * represents artifact iterations of the same release, so `1.0.0+1 > 1.0.0`
+ * and `1.0.0+2 > 1.0.0+1`. A canonical release (no suffix) is not considered
+ * newer than a suffixed one.
+ *
+ * Returns true only when `available` is strictly greater than `installed`.
+ */
+export function isNewerVersion(available, installed) {
+    var _a, _b;
+    const [aRelease = '', aBuild = ''] = available.split('+');
+    const [bRelease = '', bBuild = ''] = installed.split('+');
+    const a = aRelease.split('.').map((s) => parseInt(s, 10) || 0);
+    const b = bRelease.split('.').map((s) => parseInt(s, 10) || 0);
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const av = (_a = a[i]) !== null && _a !== void 0 ? _a : 0;
+        const bv = (_b = b[i]) !== null && _b !== void 0 ? _b : 0;
+        if (av > bv)
+            return true;
+        if (av < bv)
+            return false;
+    }
+    // Release versions are equal — compare build metadata.
+    // absent (canonical) < any suffix; numeric suffix compared numerically.
+    if (aBuild === bBuild)
+        return false;
+    if (aBuild === '')
+        return false; // canonical is not newer than suffixed
+    if (bBuild === '')
+        return true; // suffixed is newer than canonical
+    const an = parseInt(aBuild, 10);
+    const bn = parseInt(bBuild, 10);
+    if (!isNaN(an) && !isNaN(bn))
+        return an > bn;
+    return aBuild > bBuild; // lexicographic fallback for non-numeric suffixes
+}

package/dist/app/store/version.test.d.ts

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

package/dist/app/store/version.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { isNewerVersion } from './version';
+describe('isNewerVersion', () => {
+    describe('standard semver (no build metadata)', () => {
+        it('returns true when available has higher major', () => {
+            expect(isNewerVersion('2.0.0', '1.9.9')).toBe(true);
+        });
+        it('returns true when available has higher minor', () => {
+            expect(isNewerVersion('0.2.0', '0.1.9')).toBe(true);
+        });
+        it('returns true when available has higher patch', () => {
+            expect(isNewerVersion('0.1.1', '0.1.0')).toBe(true);
+        });
+        it('returns false when available is lower', () => {
+            expect(isNewerVersion('0.1.0', '1.0.0')).toBe(false);
+        });
+        it('returns false when versions are equal', () => {
+            expect(isNewerVersion('0.1.0', '0.1.0')).toBe(false);
+        });
+    });
+    describe('build metadata suffix (+N)', () => {
+        it('returns true when available has suffix and installed does not', () => {
+            expect(isNewerVersion('0.1.0+1', '0.1.0')).toBe(true);
+        });
+        it('returns false when available has no suffix and installed does', () => {
+            expect(isNewerVersion('0.1.0', '0.1.0+1')).toBe(false);
+        });
+        it('returns true when available has higher numeric suffix', () => {
+            expect(isNewerVersion('0.1.0+2', '0.1.0+1')).toBe(true);
+        });
+        it('returns false when available has lower numeric suffix', () => {
+            expect(isNewerVersion('0.1.0+1', '0.1.0+2')).toBe(false);
+        });
+        it('returns false when suffixes are equal', () => {
+            expect(isNewerVersion('0.1.0+1', '0.1.0+1')).toBe(false);
+        });
+        it('higher build suffix does not beat higher release version', () => {
+            expect(isNewerVersion('0.1.0+99', '0.2.0')).toBe(false);
+        });
+        it('higher release version beats any build suffix', () => {
+            expect(isNewerVersion('0.2.0', '0.1.0+99')).toBe(true);
+        });
+    });
+});

package/dist/apps/lifecycle.d.ts

@@ -25,6 +25,12 @@ export interface LaunchAppOptions {
      * "home" view to return to first.
      */
     skipSwitchToHome?: boolean;
+    /**
+     * Arbitrary data passed to the app at launch time. Available as
+     * `ctx.args` in `App.activate` and `App.onAppReady`.
+     * Ignored on re-entry (resume) — the app's existing context is reused.
+     */
+    args?: Record<string, unknown>;
 }
 /**
  * Launch an app by id. Activates all required shards (idempotent for

package/dist/apps/lifecycle.js

@@ -12,6 +12,7 @@
  * return-to-home (null). Boot reads it to decide whether to auto-launch.
  */
 import { createStateZones } from '../state/zones.svelte';
+import { createGestureRegistry } from '../gestures';
 import { activateShard, deactivateShard, getShardContext, registeredShards, } from '../shards/activate.svelte';
 import { attachApp, acquireAppSlotHolds, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
 import { activeApp, breadcrumbApp, getRegisteredApp, registeredApps } from './registry.svelte';
@@ -60,7 +61,7 @@ function resolveLaunchScope() {
     var _a;
     return (_a = sessionState.activeProjectId) !== null && _a !== void 0 ? _a : getActiveScopeId();
 }
-function getOrCreateAppContext(appId, scopeId) {
+function getOrCreateAppContext(appId, scopeId, args) {
     var _a;
     let ctx = appContexts.get(appId);
     if (!ctx) {
@@ -68,10 +69,12 @@ function getOrCreateAppContext(appId, scopeId) {
         const scope = scopeId !== null && scopeId !== void 0 ? scopeId : resolveLaunchScope();
         ctx = {
             scopeId: scope,
+            args: args !== null && args !== void 0 ? args : {},
             state: (schema) => createStateZones(`__app__:${appId}:scope:${scope}`, schema),
             zones: ((_a = app === null || app === void 0 ? void 0 : app.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_STATE_MANAGE))
                 ? createZoneManager()
                 : undefined,
+            gestures: createGestureRegistry(typeof document !== 'undefined' ? document.body : null),
         };
         appContexts.set(appId, ctx);
     }
@@ -156,7 +159,7 @@ export async function launchApp(id, opts = {}) {
     // refcount holds on the app's slots now (pool's factory lookup
     // happens in a microtask from this call).
     acquireAppSlotHolds();
-    void ((_f = app.activate) === null || _f === void 0 ? void 0 : _f.call(app, getOrCreateAppContext(id)));
+    void ((_f = app.activate) === null || _f === void 0 ? void 0 : _f.call(app, getOrCreateAppContext(id, undefined, opts.args)));
     activeApp.id = id;
     setActiveApp(id, new Set((_g = app.manifest.requiredShards) !== null && _g !== void 0 ? _g : []));
     void loadUserBindings(id).then(setUserBindings);

package/dist/apps/lifecycle.test.js

@@ -630,3 +630,33 @@ describe('launchApp — scenario D.1 skipLastApp option', () => {
         expect(readLastApp()).toBe('app-default-last');
     });
 });
+// ---------------------------------------------------------------------------
+// Launch args — ctx.args
+// ---------------------------------------------------------------------------
+describe('launchApp — ctx.args', () => {
+    beforeEach(resetFramework);
+    it('passes args to activate via ctx.args', async () => {
+        let receivedArgs;
+        const shard = makeShard({ manifest: makeShardManifest({ id: 'shard-args' }) });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'app-args', requiredShards: ['shard-args'] }),
+            activate: (ctx) => { receivedArgs = ctx.args; },
+        });
+        registerApp(app);
+        await launchApp('app-args', { args: { file: { path: '/doc.svg', tenantId: 'alice', binary: false } } });
+        expect(receivedArgs).toEqual({ file: { path: '/doc.svg', tenantId: 'alice', binary: false } });
+    });
+    it('defaults ctx.args to empty object when no args passed', async () => {
+        let receivedArgs;
+        const shard = makeShard({ manifest: makeShardManifest({ id: 'shard-noargs' }) });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'app-noargs', requiredShards: ['shard-noargs'] }),
+            activate: (ctx) => { receivedArgs = ctx.args; },
+        });
+        registerApp(app);
+        await launchApp('app-noargs');
+        expect(receivedArgs).toEqual({});
+    });
+});

package/dist/apps/types.d.ts

@@ -1,6 +1,7 @@
 import type { LayoutNode, LayoutTree, LayoutPreset } from '../layout/types';
 import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { StateZones } from '../state/zones.svelte';
+import type { GestureRegistry } from '../gestures';
 /**
  * One menu bar container ("File", "Edit", etc.). Apps declare these in
  * `AppManifest.menus`; when omitted, sh3-core uses DEFAULT_MENU_CONTAINERS.
@@ -95,6 +96,12 @@ export interface AppContext {
      * scope and cannot reach across scopes — exiting a scope unloads the app.
      */
     scopeId: string;
+    /**
+     * Arguments supplied by the caller at launch time via `LaunchAppOptions.args`.
+     * Defaults to `{}` when the app is launched without explicit args.
+     * Read-only — apps observe but do not mutate this object.
+     */
+    readonly args: Record<string, unknown>;
     /**
      * App-scoped state zones. The shardId underneath is the app id plus the
      * scope, so `state({ workspace: { x: 0 } }).workspace.x = 1` persists to
@@ -108,6 +115,11 @@ export interface AppContext {
      * `if (ctx.zones)` before use.
      */
     zones?: ZoneManager;
+    /**
+     * Per-app gesture binding API. Register Pan, Drag, Button, and Scroll
+     * handlers that participate in the shell's pointer arbitration protocol.
+     */
+    gestures: GestureRegistry;
 }
 /**
  * An app module. An app is a composition document — it declares required

package/dist/assets/iconIds.generated.d.ts

@@ -1,2 +1,2 @@
-export declare const ICON_IDS: readonly ["activity", "align-horizontal-justify-center", "align-horizontal-justify-end", "align-horizontal-justify-start", "app-window", "archive", "archive-restore", "axis-3d", "box", "brick-wall", "bug", "building-2", "cable", "calendar", "camera", "check", "chevron-down", "chevron-right", "circle-check", "circle-dot", "circle-minus", "circle-x", "clipboard", "clipboard-paste", "clock", "compass", "component", "copy", "cpu", "crop", "crosshair", "crown", "dollar-sign", "download", "droplet", "eraser", "euro", "external-link", "eye", "eye-off", "file", "file-archive", "file-diff", "file-plus", "file-text", "flame", "flip-horizontal-2", "flip-vertical-2", "folder", "folder-open", "folder-plus", "folder-tree", "gallery-vertical-end", "gamepad-2", "gauge", "gem", "git-branch", "git-commit-horizontal", "git-merge", "globe", "grid-2x2", "grid-3x3", "group", "hard-drive", "heart", "history", "house", "image", "info", "joystick", "key", "layers", "layout-dashboard", "layout-grid", "layout-list", "layout-panel-left", "layout-panel-top", "layout-template", "lightbulb", "link", "list-ordered", "list-tree", "lock", "log-out", "magnet", "mail", "map", "maximize", "minimize", "moon", "mouse-pointer", "move", "move-3d", "music", "navigation", "network", "notebook-pen", "palette", "pause", "pencil", "pipette", "play", "plus", "pointer", "pound-sterling", "receipt", "redo-2", "refresh-cw", "rocket", "rotate-3d", "rotate-ccw", "rotate-cw", "ruler", "save", "scissors", "scroll-text", "search", "send", "server", "settings", "shield", "skull", "sliders-horizontal", "snowflake", "sparkles", "square", "square-terminal", "star", "sun", "sword", "table-properties", "target", "texture", "timer", "trash-2", "triangle-alert", "type", "undo-2", "ungroup", "unity", "upload", "user", "users", "video", "volume-2", "wand-sparkles", "wind", "x", "zap", "zoom-in", "zoom-out"];
+export declare const ICON_IDS: readonly ["activity", "align-horizontal-justify-center", "align-horizontal-justify-end", "align-horizontal-justify-start", "app-window", "archive", "archive-restore", "axis-3d", "box", "brick-wall", "bug", "building-2", "cable", "calendar", "camera", "check", "chevron-down", "chevron-right", "circle-check", "circle-dot", "circle-minus", "circle-x", "clipboard", "clipboard-paste", "clock", "command", "compass", "component", "copy", "cpu", "crop", "crosshair", "crown", "dollar-sign", "download", "droplet", "ellipsis-vertical", "eraser", "euro", "external-link", "eye", "eye-off", "file", "file-archive", "file-diff", "file-plus", "file-text", "flame", "flip-horizontal-2", "flip-vertical-2", "folder", "folder-open", "folder-plus", "folder-tree", "gallery-vertical-end", "gamepad-2", "gauge", "gem", "git-branch", "git-commit-horizontal", "git-merge", "globe", "grid-2x2", "grid-3x3", "group", "hard-drive", "heart", "history", "house", "image", "info", "joystick", "key", "layers", "layout-dashboard", "layout-grid", "layout-list", "layout-panel-left", "layout-panel-top", "layout-template", "lightbulb", "link", "list-ordered", "list-tree", "lock", "log-out", "magnet", "mail", "map", "maximize", "menu", "minimize", "moon", "mouse-pointer", "move", "move-3d", "music", "navigation", "network", "notebook-pen", "palette", "panel-right", "panel-top", "pause", "pencil", "pipette", "play", "plus", "pointer", "pound-sterling", "receipt", "redo-2", "refresh-cw", "rocket", "rotate-3d", "rotate-ccw", "rotate-cw", "ruler", "save", "scissors", "scroll-text", "search", "send", "server", "settings", "shield", "skull", "sliders-horizontal", "snowflake", "sparkles", "square", "square-terminal", "star", "sun", "sword", "table-properties", "target", "texture", "timer", "trash-2", "triangle-alert", "type", "undo-2", "ungroup", "unity", "upload", "user", "users", "video", "volume-2", "wand-sparkles", "wind", "x", "zap", "zoom-in", "zoom-out"];
 export type IconId = (typeof ICON_IDS)[number];

package/dist/assets/iconIds.generated.js

@@ -25,6 +25,7 @@ export const ICON_IDS = [
     'clipboard',
     'clipboard-paste',
     'clock',
+    'command',
     'compass',
     'component',
     'copy',
@@ -35,6 +36,7 @@ export const ICON_IDS = [
     'dollar-sign',
     'download',
     'droplet',
+    'ellipsis-vertical',
     'eraser',
     'euro',
     'external-link',
@@ -88,6 +90,7 @@ export const ICON_IDS = [
     'mail',
     'map',
     'maximize',
+    'menu',
     'minimize',
     'moon',
     'mouse-pointer',
@@ -98,6 +101,8 @@ export const ICON_IDS = [
     'network',
     'notebook-pen',
     'palette',
+    'panel-right',
+    'panel-top',
     'pause',
     'pencil',
     'pipette',