sh3-core 0.6.0 → 0.7.1

package/dist/Shell.svelte

@@ -16,11 +16,12 @@
   import './primitives/base.css';
   import LayoutRenderer from './layout/LayoutRenderer.svelte';
   import DragPreview from './layout/DragPreview.svelte';
+  import FloatLayer from './overlays/FloatLayer.svelte';
   import type { OverlayLayer } from './overlays/types';
   import { registerLayerRoot, unregisterLayerRoot } from './overlays/roots';
+  import { bindFloatStore, unbindFloatStore, floatManager } from './overlays/float';
   import { returnToHome, isAdmin } from './api';
-  import { getActiveRoot } from './layout/store.svelte';
-  import { dockIntoActiveLayout } from './layout/inspection';
+  import { getActiveRoot, layoutStore } from './layout/store.svelte';
   import { isAuthenticated, isLocalOwner, getUser, logout } from './auth/index';
   import iconsUrl from './assets/icons.svg';
   import GuestBanner from './auth/GuestBanner.svelte';
@@ -59,12 +60,10 @@
     };
   });
 
-  // The AZERTY `²` key (top-left, below Escape) docks the terminal view
-  // into the currently-rendered layout — whichever app is active, or the
-  // home root if none. Admin-only because the shell shard is admin-gated.
-  // Provisional ergonomics shortcut; a real hotkey contribution API is
-  // DF1 in the roadmap, and dedicated floating-window placement is
-  // SH9 / DF3.
+  // The AZERTY `²` key (top-left, below Escape) opens the terminal view
+  // in a floating panel (DF3 float runtime). Admin-only because the shell
+  // shard is admin-gated. Provisional ergonomics shortcut; a real hotkey
+  // contribution API is DF1 in the roadmap.
   //
   // Bare key (no modifier) so it must be suppressed while the user is
   // typing into an input/textarea/contenteditable, or the shortcut would
@@ -83,15 +82,20 @@
         ) return;
       }
       e.preventDefault();
-      dockIntoActiveLayout({
-        slotId: `shell.terminal.${Date.now()}`,
-        viewId: 'shell:terminal',
-        label: 'Shell',
-      });
+      floatManager.open('shell:terminal', { title: 'Shell' });
     }
     window.addEventListener('keydown', onKeyDown);
     return () => window.removeEventListener('keydown', onKeyDown);
   });
+
+  $effect(() => {
+    const tree = layoutStore.tree;
+    bindFloatStore(tree.floats, () => ({
+      w: window.innerWidth,
+      h: window.innerHeight,
+    }));
+    return () => unbindFloatStore();
+  });
 </script>
 
 <div class="shell">
@@ -152,7 +156,9 @@
         style="z-index: var(--shell-z-layer-{layer});"
         bind:this={overlayRoots[name]}
       >
-        {#if name === 'drag-preview'}
+        {#if name === 'floating'}
+          <FloatLayer />
+        {:else if name === 'drag-preview'}
           <DragPreview />
         {/if}
       </div>

package/dist/api.d.ts

@@ -1,12 +1,14 @@
 export { shell } from './shellRuntime.svelte';
 export type { Shell } from './shellRuntime.svelte';
-export type { Shard, ShardManifest, ShardContext, ViewDeclaration, ViewFactory, ViewHandle, MountContext, } from './shards/types';
-export type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry, SplitDirection, SizeMode, } from './layout/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, } from './layout/types';
+export type { FloatManager, FloatOptions } from './overlays/float';
+export type { PresetManager } from './overlays/presets';
 export type { ZoneSchema, ZoneName, ZoneManager } from './state/types';
 export { PERMISSION_STATE_MANAGE } from './state/types';
 export type { StateZones } from './state/zones.svelte';
 export type { EnvState } from './env/types';
-export type { App, AppManifest, AppContext } from './apps/types';
+export type { App, AppManifest, SourceApp, SourceAppManifest, AppContext, } from './apps/types';
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome } from './apps/lifecycle';
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
@@ -24,5 +26,7 @@ export declare const capabilities: {
     readonly hotInstall: boolean;
 };
 export type { ServerShard, ServerShardContext } from './server-shard/types';
+export type { Verb } from './verbs/types';
+export { listVerbs } from './shards/registry';
 export { VERSION } from './version';
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/api.js

@@ -44,6 +44,7 @@ export const capabilities = {
     /** Whether this target supports hot-installing packages via dynamic import from blob URL. */
     hotInstall: typeof Blob !== 'undefined' && typeof URL.createObjectURL === 'function',
 };
+export { listVerbs } from './shards/registry';
 // Package version.
 export { VERSION } from './version';
 // Theme token override API (shell-level theming support).

package/dist/app/admin/adminApp.js

@@ -3,11 +3,12 @@
  * Framework-shipped: registered in host.ts during bootstrap.
  * Admin-gated via manifest flag (ADR-011).
  */
+import { VERSION } from '../../version';
 export const adminApp = {
     manifest: {
         id: 'sh3-admin-app',
         label: 'Admin',
-        version: '0.1.0',
+        version: VERSION,
         requiredShards: ['sh3-admin'],
         layoutVersion: 1,
         admin: true,

package/dist/app/admin/adminShard.svelte.js

@@ -15,13 +15,14 @@ import UsersView from './UsersView.svelte';
 import AuthSettingsView from './AuthSettingsView.svelte';
 import SystemView from './SystemView.svelte';
 import ApiKeysView from './ApiKeysView.svelte';
+import { VERSION } from '../../version';
 /** Module-level server URL, set during activate. */
 export let adminServerUrl = '';
 export const adminShard = {
     manifest: {
         id: 'sh3-admin',
         label: 'Admin',
-        version: '0.1.0',
+        version: VERSION,
         views: [
             { id: 'sh3-admin:users', label: 'Users' },
             { id: 'sh3-admin:auth', label: 'Auth Settings' },

package/dist/app/store/StoreView.svelte

@@ -7,7 +7,7 @@
    */
 
   import { storeContext } from './storeShard.svelte';
-  import { fetchBundle, buildPackageMeta } from '../../registry/client';
+  import { fetchBundle, fetchServerBundle, buildPackageMeta } from '../../registry/client';
   import { installPackage } from '../../registry/installer';
   import { serverInstallPackage } from '../../env/client';
   import { contract } from '../../contract';
@@ -100,11 +100,17 @@
     installError = null;
 
     try {
-      // 1. Fetch and integrity-verify the bundle from the registry.
+      // 1. Fetch and integrity-verify the client bundle from the registry.
       const bundle = await fetchBundle(pkg.latest, pkg.sourceRegistry);
       const meta = buildPackageMeta(pkg, pkg.latest);
 
-      // 2. Upload to server for persistent storage.
+      // 2. Fetch the server bundle if the package declares one.
+      let serverBundle: ArrayBuffer | undefined;
+      if (pkg.latest.serverBundleUrl) {
+        serverBundle = await fetchServerBundle(pkg.latest, pkg.sourceRegistry);
+      }
+
+      // 3. Upload to server for persistent storage.
       const manifest = {
         id: meta.id,
         type: meta.type,
@@ -114,13 +120,13 @@
         sourceRegistry: meta.sourceRegistry,
         installedAt: new Date().toISOString(),
       };
-      const serverResult = await serverInstallPackage(manifest, bundle);
+      const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
       if (!serverResult.ok) {
         installError = serverResult.error ?? 'Server install failed';
         return;
       }
 
-      // 3. Also install locally for immediate hot-load.
+      // 4. Also install locally for immediate hot-load.
       const result = await installPackage(bundle, meta);
       if (!result.success) {
         console.warn(`[sh3-store] Server install ok but local hot-load failed: ${result.error}`);

package/dist/app/store/storeApp.js

@@ -6,11 +6,12 @@
  * Framework-shipped: registered in host.ts during bootstrap.
  * Admin-gated via manifest flag (ADR-011).
  */
+import { VERSION } from '../../version';
 export const storeApp = {
     manifest: {
         id: 'sh3-store-app',
         label: 'Package Store',
-        version: '0.2.1',
+        version: VERSION,
         requiredShards: ['sh3-store'],
         layoutVersion: 1,
         admin: true,

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

@@ -14,10 +14,12 @@
 import { mount, unmount } from 'svelte';
 import StoreView from './StoreView.svelte';
 import InstalledView from './InstalledView.svelte';
-import { fetchRegistries, fetchBundle, buildPackageMeta } from '../../registry/client';
+import { fetchRegistries, fetchBundle, fetchServerBundle, buildPackageMeta } from '../../registry/client';
 import { installPackage, listInstalledPackages } from '../../registry/installer';
 import { loadBundle, savePackage } from '../../registry/storage';
 import { serverInstallPackage, fetchServerPackages } from '../../env/client';
+import { VERSION } from '../../version';
+import { installVerb, uninstallVerb, appinfoVerb } from './verbs';
 /**
  * Compare two semver-like version strings.
  * Returns true only if `available` is strictly greater than `installed`.
@@ -48,7 +50,7 @@ export const storeShard = {
     manifest: {
         id: 'sh3-store',
         label: 'Package Store',
-        version: '0.2.1',
+        version: VERSION,
         views: [
             { id: 'sh3-store:browse', label: 'Store' },
             { id: 'sh3-store:installed', label: 'Installed' },
@@ -139,8 +141,12 @@ export const storeShard = {
             const installedRecord = state.ephemeral.installed.find((p) => p.id === id);
             if (!installedRecord)
                 return;
-            // 1. Fetch new bundle.
+            // 1. Fetch new bundle(s).
             const bundle = await fetchBundle(catalogEntry.latest, catalogEntry.sourceRegistry);
+            let serverBundle;
+            if (catalogEntry.latest.serverBundleUrl) {
+                serverBundle = await fetchServerBundle(catalogEntry.latest, catalogEntry.sourceRegistry);
+            }
             const meta = buildPackageMeta(catalogEntry, catalogEntry.latest);
             // 2. Snapshot current state for rollback.
             const oldBundle = await loadBundle(id);
@@ -155,7 +161,7 @@ export const storeShard = {
                 sourceRegistry: meta.sourceRegistry,
                 installedAt: new Date().toISOString(),
             };
-            const serverResult = await serverInstallPackage(manifest, bundle);
+            const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
             if (!serverResult.ok) {
                 throw new Error((_a = serverResult.error) !== null && _a !== void 0 ? _a : 'Server update failed');
             }
@@ -208,6 +214,10 @@ export const storeShard = {
         };
         ctx.registerView('sh3-store:browse', browseFactory);
         ctx.registerView('sh3-store:installed', installedFactory);
+        // Store verbs — registered as sh3-store:install, sh3-store:uninstall, sh3-store:appinfo
+        ctx.registerVerb(installVerb);
+        ctx.registerVerb(uninstallVerb);
+        ctx.registerVerb(appinfoVerb);
         // refreshInstalled can run immediately (hits server, no env needed).
         refreshInstalled();
     },

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

@@ -0,0 +1,4 @@
+import type { Verb } from '../../verbs/types';
+export declare const installVerb: Verb;
+export declare const uninstallVerb: Verb;
+export declare const appinfoVerb: Verb;

package/dist/app/store/verbs.js

@@ -0,0 +1,220 @@
+/*
+ * Store verbs — shell-accessible commands for the sh3-store shard.
+ *
+ * Registered during storeShard.activate() via ctx.registerVerb().
+ * Auto-prefixed to sh3-store:install, sh3-store:uninstall, sh3-store:appinfo.
+ */
+import { storeContext } from './storeShard.svelte';
+import { fetchBundle, fetchServerBundle, buildPackageMeta } from '../../registry/client';
+import { installPackage } from '../../registry/installer';
+import { serverInstallPackage, serverUninstallPackage } from '../../env/client';
+import { uninstallPackage } from '../../registry/installer';
+function findInCatalog(id) {
+    return storeContext.state.ephemeral.catalog.find((p) => p.entry.id === id);
+}
+function findInstalled(id) {
+    return storeContext.state.ephemeral.installed.find((p) => p.id === id);
+}
+export const installVerb = {
+    name: 'install',
+    summary: 'Install a package by id from the catalog.',
+    async run(ctx, args) {
+        var _a;
+        const id = args[0];
+        if (!id) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: sh3-store:install <package-id>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const existing = findInstalled(id);
+        if (existing) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `${id} is already installed (v${existing.version})`,
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const pkg = findInCatalog(id);
+        if (!pkg) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `package "${id}" not found in catalog — try refreshing the store`,
+                level: 'error',
+                ts: Date.now(),
+            });
+            return;
+        }
+        ctx.scrollback.push({
+            kind: 'status',
+            text: `installing ${id} v${pkg.latest.version}...`,
+            level: 'info',
+            ts: Date.now(),
+        });
+        try {
+            const bundle = await fetchBundle(pkg.latest, pkg.sourceRegistry);
+            const meta = buildPackageMeta(pkg, pkg.latest);
+            let serverBundle;
+            if (pkg.latest.serverBundleUrl) {
+                serverBundle = await fetchServerBundle(pkg.latest, pkg.sourceRegistry);
+            }
+            const manifest = {
+                id: meta.id,
+                type: meta.type,
+                label: pkg.entry.label,
+                version: meta.version,
+                contractVersion: meta.contractVersion,
+                sourceRegistry: meta.sourceRegistry,
+                installedAt: new Date().toISOString(),
+            };
+            const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
+            if (!serverResult.ok) {
+                ctx.scrollback.push({
+                    kind: 'status',
+                    text: `install failed: ${(_a = serverResult.error) !== null && _a !== void 0 ? _a : 'server error'}`,
+                    level: 'error',
+                    ts: Date.now(),
+                });
+                return;
+            }
+            const result = await installPackage(bundle, meta);
+            if (!result.success) {
+                ctx.scrollback.push({
+                    kind: 'status',
+                    text: `server ok but local hot-load failed: ${result.error}`,
+                    level: 'warn',
+                    ts: Date.now(),
+                });
+            }
+            await storeContext.refreshInstalled();
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `installed ${id} v${pkg.latest.version}`,
+                level: 'info',
+                ts: Date.now(),
+            });
+        }
+        catch (err) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `install failed: ${err instanceof Error ? err.message : String(err)}`,
+                level: 'error',
+                ts: Date.now(),
+            });
+        }
+    },
+};
+export const uninstallVerb = {
+    name: 'uninstall',
+    summary: 'Uninstall an installed package by id.',
+    async run(ctx, args) {
+        const id = args[0];
+        if (!id) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: sh3-store:uninstall <package-id>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const existing = findInstalled(id);
+        if (!existing) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `package "${id}" is not installed`,
+                level: 'error',
+                ts: Date.now(),
+            });
+            return;
+        }
+        ctx.scrollback.push({
+            kind: 'status',
+            text: `uninstalling ${id}...`,
+            level: 'info',
+            ts: Date.now(),
+        });
+        try {
+            await serverUninstallPackage(id);
+            await uninstallPackage(id);
+            await storeContext.refreshInstalled();
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `uninstalled ${id}`,
+                level: 'info',
+                ts: Date.now(),
+            });
+        }
+        catch (err) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `uninstall failed: ${err instanceof Error ? err.message : String(err)}`,
+                level: 'error',
+                ts: Date.now(),
+            });
+        }
+    },
+};
+export const appinfoVerb = {
+    name: 'appinfo',
+    summary: 'Show info about a package (installed status, version, catalog details).',
+    async run(ctx, args) {
+        const id = args[0];
+        if (!id) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: sh3-store:appinfo <package-id>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const installed = findInstalled(id);
+        const catalogEntry = findInCatalog(id);
+        if (!installed && !catalogEntry) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `package "${id}" not found in catalog or installed list`,
+                level: 'error',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const lines = [];
+        lines.push(`--- ${id} ---`);
+        if (installed) {
+            lines.push(`  installed: yes`);
+            lines.push(`  version:   ${installed.version}`);
+            lines.push(`  type:      ${installed.type}`);
+            lines.push(`  contract:  v${installed.contractVersion}`);
+            lines.push(`  source:    ${installed.sourceRegistry}`);
+            if (installed.installedAt) {
+                lines.push(`  installed: ${installed.installedAt}`);
+            }
+        }
+        else {
+            lines.push(`  installed: no`);
+        }
+        if (catalogEntry) {
+            lines.push(`  catalog:   yes`);
+            lines.push(`  latest:    ${catalogEntry.latest.version}`);
+            lines.push(`  label:     ${catalogEntry.entry.label}`);
+            lines.push(`  author:    ${catalogEntry.entry.author.name}`);
+            lines.push(`  desc:      ${catalogEntry.entry.description}`);
+        }
+        else {
+            lines.push(`  catalog:   no (not in any configured registry)`);
+        }
+        ctx.scrollback.push({
+            kind: 'text',
+            stream: 'stdout',
+            chunks: [lines.join('\n') + '\n'],
+            ts: Date.now(),
+        });
+    },
+};

package/dist/apps/terminal/manifest.js

@@ -4,10 +4,11 @@
  * Framework-shipped: registered in host.ts during bootstrap.
  * Requires the `shell` shard which provides the `shell:terminal` view.
  */
+import { VERSION } from '../../version';
 export const manifest = {
     id: 'terminal',
     label: 'Terminal',
-    version: '0.1.0',
+    version: VERSION,
     requiredShards: ['shell'],
     layoutVersion: 1,
 };

package/dist/apps/types.d.ts

@@ -1,17 +1,19 @@
-import type { LayoutNode } from '../layout/types';
+import type { LayoutNode, LayoutTree, LayoutPreset } from '../layout/types';
 import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { StateZones } from '../state/zones.svelte';
 /**
- * Static description of an app. Declared by every app module and read by
- * the shell launcher to populate the home screen list without running any
- * activation code.
+ * Static description of an app as observed by the framework at runtime.
+ * `version` is always present here: externally installed apps have it
+ * stamped by the installer from the registry entry, in-tree apps import
+ * it from `VERSION` (auto-generated from `sh3-core`'s `package.json`).
+ * See ADR-013.
  */
 export interface AppManifest {
     /** Unique app identifier. Must match the app's registration key. */
     id: string;
     /** Human-readable display name shown in the launcher. */
     label: string;
-    /** Semver string for the app package. */
+    /** Semver version string. Always present at load time — see `SourceAppManifest` for what authors write. */
     version: string;
     /**
      * Shard ids this app requires. All required shards are activated at
@@ -71,8 +73,12 @@ export interface AppContext {
 export interface App {
     /** Static manifest describing the app and its requirements. */
     manifest: AppManifest;
-    /** Starting layout tree. Used on first launch or when the persisted layout version mismatches. */
-    initialLayout: LayoutNode;
+    /**
+     * App's default layout — accepts three shapes: a bare LayoutNode
+     * (legacy), a LayoutTree (single-preset with floats), or an array of
+     * LayoutPresets (multiple named layouts). Normalized at load time.
+     */
+    initialLayout: LayoutNode | LayoutTree | LayoutPreset[];
     /** Optional hook called after all required shards are active and the layout is attached. */
     activate?(ctx: AppContext): void | Promise<void>;
     /** Optional hook called before the app's shards are deactivated and the layout is detached. */
@@ -91,3 +97,18 @@ export interface App {
      */
     resume?(ctx: AppContext): void | Promise<void>;
 }
+/**
+ * Source-declared shape of an app manifest — what external package authors
+ * write. `version` is omitted because it would duplicate `package.json.version`;
+ * the framework injects it at load time. See ADR-013.
+ */
+export type SourceAppManifest = Omit<AppManifest, 'version'>;
+/**
+ * Source-level shape of an app as written by external package authors.
+ * Carries a `SourceAppManifest` (no `version`). The framework stamps
+ * `version` from the registry entry's `PackageVersion.version` at install
+ * time, after which the object is observed as a full `App`. See ADR-013.
+ */
+export interface SourceApp extends Omit<App, 'manifest'> {
+    manifest: SourceAppManifest;
+}

package/dist/build.d.ts

@@ -43,7 +43,10 @@ export interface Sh3ArtifactOptions {
  * After Vite's lib build completes, this plugin:
  *   1. Finds the entry chunk and renames it to client.js
  *   2. Optionally copies a pre-built server bundle as server.js
- *   3. Extracts manifest fields (id, label, version, type) from the source
- *   4. Writes manifest.json alongside the bundles
+ *   3. Extracts manifest fields (id, label, type) from the source
+ *   4. Reads `version` from `package.json.version` — the authoritative
+ *      source per ADR-013. A literal `version:` in a source manifest is
+ *      ignored; only `package.json.version` matters for the artifact.
+ *   5. Writes manifest.json alongside the bundles
  */
 export declare function sh3Artifact(options?: Sh3ArtifactOptions): Plugin;

package/dist/build.js

@@ -89,8 +89,11 @@ export function sh3CssInline() {
  * After Vite's lib build completes, this plugin:
  *   1. Finds the entry chunk and renames it to client.js
  *   2. Optionally copies a pre-built server bundle as server.js
- *   3. Extracts manifest fields (id, label, version, type) from the source
- *   4. Writes manifest.json alongside the bundles
+ *   3. Extracts manifest fields (id, label, type) from the source
+ *   4. Reads `version` from `package.json.version` — the authoritative
+ *      source per ADR-013. A literal `version:` in a source manifest is
+ *      ignored; only `package.json.version` matters for the artifact.
+ *   5. Writes manifest.json alongside the bundles
  */
 export function sh3Artifact(options = {}) {
     let outDir = '';
@@ -145,10 +148,11 @@ export function sh3Artifact(options = {}) {
             }
             const type = hasShard && hasApp ? 'combo' : hasApp ? 'app' : 'shard';
             /**
-             * Extract id, label, and version from the manifest object block that
-             * contains `anchor`. Walks backwards from the anchor to find the
-             * opening `{`, then forward to find the matching `}`, and extracts
-             * fields from within that slice.
+             * Extract id and label from the manifest object block that contains
+             * `anchor`. Walks backwards from the anchor to find the opening `{`,
+             * then forward to find the matching `}`, and extracts fields from
+             * within that slice. `version` is NOT extracted from the source —
+             * per ADR-013 the authoritative value is `package.json.version`.
              */
             function extractFromBlock(anchor) {
                 const anchorMatch = anchor.exec(source);
@@ -190,29 +194,36 @@ export function sh3Artifact(options = {}) {
                 return {
                     id: get(/\bid\s*:\s*["']([^"']+)["']/),
                     label: get(/\blabel\s*:\s*["']([^"']+)["']/),
-                    version: get(/\bversion\s*:\s*["']([^"']+)["']/),
                 };
             }
             // App first, then Shard.
             const extracted = (_a = extractFromBlock(/\brequiredShards\s*:\s*\[/)) !== null && _a !== void 0 ? _a : extractFromBlock(/\bviews\s*:\s*\[/);
-            const { id, label, version } = extracted;
+            const { id, label } = extracted;
             // --- Optional server bundle ---
             let hasServer = false;
             if (options.serverEntry && existsSync(options.serverEntry)) {
                 copyFileSync(options.serverEntry, join(outDir, 'server.js'));
                 hasServer = true;
             }
-            // --- Read fallback metadata from package.json ---
+            // --- Read metadata from package.json ---
+            // `version` is authoritative per ADR-013; `description` and `author`
+            // are fallbacks when the user doesn't pass overrides.
+            let pkgVersion;
             let pkgDescription;
             let pkgAuthor;
             try {
                 const pkg = JSON.parse(readFileSync('package.json', 'utf-8'));
+                pkgVersion = typeof pkg.version === 'string' ? pkg.version : undefined;
                 pkgDescription = typeof pkg.description === 'string' ? pkg.description : undefined;
                 pkgAuthor = typeof pkg.author === 'string'
                     ? pkg.author
                     : typeof ((_b = pkg.author) === null || _b === void 0 ? void 0 : _b.name) === 'string' ? pkg.author.name : undefined;
             }
             catch ( /* no package.json or unreadable */_g) { /* no package.json or unreadable */ }
+            if (!pkgVersion) {
+                throw new Error('[sh3-artifact] Missing "version" in package.json. Per ADR-013 the package '
+                    + 'version is read from package.json, not from the source manifest.');
+            }
             // --- Write manifest.json ---
             const overrides = (_c = options.manifest) !== null && _c !== void 0 ? _c : {};
             const finalDescription = (_d = overrides.description) !== null && _d !== void 0 ? _d : pkgDescription;
@@ -223,7 +234,7 @@ export function sh3Artifact(options = {}) {
             if (!finalAuthor) {
                 throw new Error('[sh3-artifact] Missing "author". Add it to package.json or pass it via sh3Artifact({ manifest: { author } }).');
             }
-            const manifest = Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: version || '0.0.0', contractVersion: 1, client: 'client.js' }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), overrides);
+            const manifest = Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: pkgVersion, contractVersion: 1, client: 'client.js' }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), overrides);
             writeFileSync(join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
             // --- Log summary ---
             const files = ['manifest.json', 'client.js'];