sh3-core 0.20.2 → 0.21.0

package/dist/BrandSlot.svelte

@@ -13,7 +13,7 @@
   import { getLiveDispatcherState } from './actions/state.svelte';
   import { launchApp, returnToHome } from './apps/lifecycle';
   import { getBreadcrumbAppId, getRegisteredApp } from './apps/registry.svelte';
-  import { sessionState, setActiveProjectId } from './projects/session-state.svelte';
+  import { sessionState, switchProjectScope } from './projects/session-state.svelte';
   import { projectsState } from './projects-shard/projectsShard.svelte';
 
   const activeAppId = $derived(getLiveDispatcherState().activeAppId);
@@ -48,7 +48,7 @@
   }
 
   function exitProject() {
-    setActiveProjectId(null);
+    switchProjectScope(null);
   }
 
   function reenterProjectHome() {

package/dist/actions/ctx-actions.svelte.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { MemoryDocumentBackend } from '../documents/backends';
-import { __setDocumentBackend, __setTenantId } from '../documents/config';
+import { __setDocumentBackend, __setActiveScope } from '../documents/config';
 import { registerShard, activateShard, __resetShardRegistryForTest, } from '../shards/activate.svelte';
 import { __resetViewRegistryForTest } from '../shards/registry';
 import { __resetActionsRegistryForTest } from './registry';
@@ -14,7 +14,7 @@ describe('ShardContext.listActions / runAction (integration)', () => {
         __resetActionsRegistryForTest();
         __resetDispatcherStateForTest();
         __setDocumentBackend(new MemoryDocumentBackend());
-        __setTenantId('tenant-test');
+        __setActiveScope('tenant-test');
     });
     it('listActions enumerates actions registered by other shards', async () => {
         registerShard({

package/dist/api.d.ts

@@ -40,9 +40,9 @@ export type { ColorPickOptions, ColorContribution, ColorApi, } from './color/api
 export { COLOR_PICKER_POINT } from './color/api';
 export { registeredShards, activeShards, erroredShards } from './shards/activate.svelte';
 export type { ShardErrorEntry } from './shards/activate.svelte';
-export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
+export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, RemoteInstallRequest, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
-export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
+export { fetchRegistries, fetchArchive, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
 export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError, type ShardContextKeys, type ApiKeyPublic, type MintOpts, } from './keys/types';
 export { registerConsentListener, resolveConsent, type ConsentRequest } from './keys/consent.svelte';

package/dist/api.js

@@ -43,7 +43,7 @@ export { COLOR_PICKER_POINT } from './color/api';
 // addition: diagnostic used to reach `activate.svelte` directly via $lib;
 // the package boundary requires routing through the public surface.
 export { registeredShards, activeShards, erroredShards } from './shards/activate.svelte';
-export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
+export { fetchRegistries, fetchArchive, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
 // Key mint/revoke types — client shards that declare `keys:mint` get ctx.keys.
 export { PERMISSION_KEYS_MINT, ScopeEscalationError, ConsentDeniedError, } from './keys/types';

package/dist/app/store/StoreView.svelte

@@ -7,11 +7,12 @@
    */
 
   import { storeContext } from './storeShard.svelte';
-  import { fetchBundle, fetchServerBundle, buildPackageMeta } from '../../registry/client';
+  import { fetchArchive, buildPackageMeta } from '../../registry/client';
+  import { readFileFromArchive, readManifestFromArchive } from '../../registry/archive';
   import { installPackage } from '../../registry/installer';
   import { loadBundleModule, type LoadedBundle } from '../../registry/loader';
   import { extractBundlePermissions } from '../../registry/permission-descriptions';
-  import { serverInstallPackage } from '../../env/client';
+  import { requestServerInstall } from '../../env/client';
   import { checkBundleFetch } from '../../registry/checkFetch';
   import { contract } from '../../contract';
   import type { ResolvedPackage } from '../../registry/client';
@@ -36,9 +37,8 @@
     pkg: ResolvedPackage;
     permissions: string[];
     loaded: LoadedBundle;
-    bundle: ArrayBuffer;
+    archiveBytes: Uint8Array;
     meta: ReturnType<typeof buildPackageMeta>;
-    serverBundle: ArrayBuffer | undefined;
     warnings: string[];
   }>(null);
 
@@ -171,26 +171,20 @@
     installError = null;
 
     try {
-      // 1. Fetch and integrity-verify the client bundle from the registry.
-      const bundle = await fetchBundle(pkg.latest, pkg.sourceRegistry);
+      // 1. Fetch and integrity-verify the archive from the registry.
+      const archiveBytes = await fetchArchive(pkg.latest, pkg.sourceRegistry);
       const meta = buildPackageMeta(pkg, pkg.latest);
 
-      // 2. Load the module once, extract permissions for the confirmation
-      //    modal, and reuse the loaded reference on install.
-      const loaded = await loadBundleModule(bundle);
-      const permissions = extractBundlePermissions(loaded);
+      // 2. Extract client.js, load the module to get permissions for the modal.
+      const clientJs = readFileFromArchive(archiveBytes, 'client.js');
+      const loaded = clientJs ? await loadBundleModule(clientJs) : null;
+      const permissions = loaded ? extractBundlePermissions(loaded) : [];
 
-      // 3. Fetch the server bundle upfront so the modal is the last blocker.
-      let serverBundle: ArrayBuffer | undefined;
-      if (pkg.latest.serverBundleUrl) {
-        serverBundle = await fetchServerBundle(pkg.latest, pkg.sourceRegistry);
-      }
-
-      // 4. Show the confirmation modal. The actual install happens in
+      // 3. Show the confirmation modal. The actual install happens in
       //    confirmInstall() once the user clicks Install.
-      const bundleText = new TextDecoder().decode(new Uint8Array(bundle));
+      const bundleText = clientJs ? new TextDecoder().decode(new Uint8Array(clientJs)) : '';
       const warnings = checkBundleFetch(bundleText);
-      installModal = { pkg, permissions, loaded, bundle, meta, serverBundle, warnings };
+      installModal = { pkg, permissions, loaded: loaded!, archiveBytes, meta, warnings };
     } catch (err) {
       installError = err instanceof Error ? err.message : String(err);
       const next = new Set(installingIds);
@@ -204,29 +198,26 @@
     if (!ctxModal) return;
     installModal = null;
 
-    const { pkg, loaded, bundle, meta, serverBundle } = ctxModal;
+    const { pkg, loaded, archiveBytes, meta } = ctxModal;
     const id = pkg.entry.id;
 
     try {
-      const manifest = {
-        id: meta.id,
-        type: meta.type,
-        label: pkg.entry.label,
-        version: meta.version,
-        contractVersion: meta.contractVersion,
-        sourceRegistry: meta.sourceRegistry,
-        requiredShards: pkg.latest.requires?.map((r) => r.id) ?? [],
-        installedAt: new Date().toISOString(),
-      };
-      const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
+      const serverResult = await requestServerInstall(pkg.sourceRegistry, pkg.entry.id, meta.version);
       if (!serverResult.ok) {
-        installError = serverResult.error ?? 'Server install failed';
+        let errMsg = serverResult.error ?? 'Server install failed';
+        if (serverResult.code === 'missing-shards' && serverResult.missing) {
+          errMsg = `missing required shard(s): ${serverResult.missing.map((m: { id: string }) => m.id).join(', ')}`;
+        }
+        installError = errMsg;
         return;
       }
 
-      const result = await installPackage(bundle, meta, { loaded });
-      if (!result.success) {
-        console.warn(`[sh3-store] Server install ok but local hot-load failed: ${result.error}`);
+      const clientJs = readFileFromArchive(archiveBytes, 'client.js');
+      if (clientJs) {
+        const result = await installPackage(clientJs, meta, { loaded });
+        if (!result.success) {
+          console.warn(`[sh3-store] Server install ok but local hot-load failed: ${result.error}`);
+        }
       }
 
       await ctx.refreshInstalled();

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

@@ -17,13 +17,14 @@
  */
 import { mount, unmount } from 'svelte';
 import StoreView from './StoreView.svelte';
-import { fetchRegistries, fetchBundle, fetchServerBundle, buildPackageMeta } from '../../registry/client';
+import { fetchRegistries, fetchArchive, buildPackageMeta } from '../../registry/client';
 import { installPackage, listInstalledPackages } from '../../registry/installer';
 import { uninstallPackage as installerUninstallPackage } from '../../registry/installer';
 import { loadBundle, loadMeta, savePackage } from '../../registry/storage';
 import { loadBundleModule } from '../../registry/loader';
 import { extractBundlePermissions } from '../../registry/permission-descriptions';
-import { serverInstallPackage, fetchServerPackages, serverUninstallPackage } from '../../env/client';
+import { readFileFromArchive } from '../../registry/archive';
+import { requestServerInstall, fetchServerPackages, serverUninstallPackage } from '../../env/client';
 import { VERSION } from '../../version';
 import { installVerb, uninstallVerb, appinfoVerb, updateVerb } from './verbs';
 import { isNewerVersion } from './version';
@@ -147,7 +148,7 @@ export const storeShard = {
             await ctx.envUpdate({ registries });
         }
         async function updatePackage(id, confirmPermissionChange, version) {
-            var _a, _b, _c, _d;
+            var _a, _b;
             // Source the catalog entry. Without an explicit version we use the
             // updatable map (which encodes the "newer than installed" check); with a
             // version we look up the package in the full catalog so downgrades and
@@ -165,77 +166,62 @@ export const storeShard = {
             if (!installedRecord)
                 return;
             const picked = pickVersion(catalogEntry, version);
-            // 1. Fetch new bundle(s).
-            const bundle = await fetchBundle(picked, catalogEntry.sourceRegistry);
-            let serverBundle;
-            if (picked.serverBundleUrl) {
-                serverBundle = await fetchServerBundle(picked, catalogEntry.sourceRegistry);
-            }
+            // 1. Fetch archive (verified against SRI).
+            const archiveBytes = await fetchArchive(picked, catalogEntry.sourceRegistry);
             const meta = buildPackageMeta(catalogEntry, picked);
-            // 2. Load the module once for permission extraction and install reuse.
-            const loaded = await loadBundleModule(bundle);
-            const newPerms = extractBundlePermissions(loaded);
-            // 3. Look up the locally persisted old permissions (server-sourced
-            //    installed list doesn't carry permissions — per spec they live
-            //    in the local IndexedDB record).
+            // 2. Extract client.js for permission check and local install.
+            const clientJs = readFileFromArchive(archiveBytes, 'client.js');
+            // 3. Load module for permission extraction (if client bundle present).
+            let loaded;
+            let newPerms = [];
+            if (clientJs) {
+                loaded = await loadBundleModule(clientJs);
+                newPerms = extractBundlePermissions(loaded);
+            }
+            // 4. Look up the locally persisted old permissions.
             let oldPerms = [];
             try {
                 const localMeta = await loadMeta(id);
                 if (localMeta === null || localMeta === void 0 ? void 0 : localMeta.permissions)
                     oldPerms = localMeta.permissions;
             }
-            catch (_e) {
-                // No local record (e.g. installed on a different browser); treat as
-                // empty. The diff will show all new permissions as additions.
+            catch (_c) {
+                // No local record; treat as empty.
             }
-            // 4. If the permission set changed and a confirmation callback was
-            //    provided, await the user's decision before touching the server.
+            // 5. If the permission set changed, await the user's decision.
             const { added, removed } = diffPermissions(oldPerms, newPerms);
             if ((added.length > 0 || removed.length > 0) && confirmPermissionChange) {
                 const ok = await confirmPermissionChange(added, removed);
                 if (!ok)
                     return;
             }
-            // 5. Snapshot current state for rollback. Preserve the locally-known
-            //    permissions so the rollback write still satisfies the InstalledPackage
-            //    contract (installedRecord came from the server-sourced list which
-            //    lacks permissions).
+            // 6. Snapshot current state for rollback.
             const oldBundle = await loadBundle(id);
             const oldRecord = Object.assign(Object.assign({}, installedRecord), { permissions: oldPerms });
-            // 6. Push to server.
-            const manifest = {
-                id: meta.id,
-                type: meta.type,
-                label: catalogEntry.entry.label,
-                version: meta.version,
-                contractVersion: meta.contractVersion,
-                sourceRegistry: meta.sourceRegistry,
-                installedAt: new Date().toISOString(),
-                requiredShards: (_b = (_a = picked.requires) === null || _a === void 0 ? void 0 : _a.map((r) => r.id)) !== null && _b !== void 0 ? _b : [],
-            };
-            const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
+            // 7. Tell server to install autonomously from the registry.
+            const serverResult = await requestServerInstall(catalogEntry.sourceRegistry, id, picked.version);
             if (!serverResult.ok) {
-                let message = (_c = serverResult.error) !== null && _c !== void 0 ? _c : 'Server update failed';
+                let message = (_a = serverResult.error) !== null && _a !== void 0 ? _a : 'Server update failed';
                 if (serverResult.code === 'missing-shards' && serverResult.missing) {
                     const ids = serverResult.missing.map((m) => m.id).join(', ');
                     message = `missing required shard(s): ${ids}`;
                 }
                 throw new Error(message);
             }
-            // 7. Install locally (overwrites IndexedDB + re-registers). Reuse the
-            //    already-loaded bundle so the ESM is not evaluated twice.
-            const result = await installPackage(bundle, meta, { loaded });
-            if (!result.success) {
-                // Rollback: restore old bundle and metadata.
-                if (oldBundle) {
-                    try {
-                        await savePackage(id, oldBundle, oldRecord);
-                    }
-                    catch (rollbackErr) {
-                        console.warn(`[sh3-store] Rollback failed for "${id}":`, rollbackErr instanceof Error ? rollbackErr.message : rollbackErr);
+            // 8. Install locally from the already-fetched archive.
+            if (clientJs) {
+                const result = await installPackage(clientJs, meta, { loaded });
+                if (!result.success) {
+                    if (oldBundle) {
+                        try {
+                            await savePackage(id, oldBundle, oldRecord);
+                        }
+                        catch (rollbackErr) {
+                            console.warn(`[sh3-store] Rollback failed for "${id}":`, rollbackErr instanceof Error ? rollbackErr.message : rollbackErr);
+                        }
                     }
+                    throw new Error((_b = result.error) !== null && _b !== void 0 ? _b : 'Local install failed during update');
                 }
-                throw new Error((_d = result.error) !== null && _d !== void 0 ? _d : 'Local install failed during update');
             }
             await refreshInstalled();
         }

package/dist/app/store/verbs.js

@@ -5,9 +5,10 @@
  * 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 { fetchArchive, buildPackageMeta } from '../../registry/client';
+import { readManifestFromArchive, readFileFromArchive } from '../../registry/archive';
+import { requestServerInstall } from '../../env/client';
 import { installPackage } from '../../registry/installer';
-import { serverInstallPackage } from '../../env/client';
 function findInCatalog(id) {
     return storeContext.state.ephemeral.catalog.find((p) => p.entry.id === id);
 }
@@ -19,7 +20,7 @@ export const installVerb = {
     summary: 'Install a package by id from the catalog.',
     programmatic: true,
     async run(ctx, args) {
-        var _a, _b, _c;
+        var _a;
         const id = args[0];
         if (!id) {
             ctx.scrollback.push({
@@ -50,68 +51,36 @@ export const installVerb = {
             });
             return;
         }
-        ctx.scrollback.push({
-            kind: 'status',
-            text: `installing ${id} v${pkg.latest.version}...`,
-            level: 'info',
-            ts: Date.now(),
-        });
+        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(),
-                requiredShards: (_b = (_a = pkg.latest.requires) === null || _a === void 0 ? void 0 : _a.map((r) => r.id)) !== null && _b !== void 0 ? _b : [],
-            };
-            const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
+            // 1. Download archive for permission modal (future) and client local install
+            const archiveBytes = await fetchArchive(pkg.latest, pkg.sourceRegistry);
+            // 2. Extract manifest (permission modal reads from it)
+            readManifestFromArchive(archiveBytes);
+            // 3. Tell server to install autonomously
+            const serverResult = await requestServerInstall(pkg.sourceRegistry, id, pkg.latest.version);
             if (!serverResult.ok) {
-                let text = `install failed: ${(_c = serverResult.error) !== null && _c !== void 0 ? _c : 'server error'}`;
+                let text = `install failed: ${(_a = serverResult.error) !== null && _a !== void 0 ? _a : 'server error'}`;
                 if (serverResult.code === 'missing-shards' && serverResult.missing) {
-                    const ids = serverResult.missing.map((m) => m.id).join(', ');
-                    text = `install failed: missing required shard(s): ${ids}`;
+                    text = `install failed: missing required shard(s): ${serverResult.missing.map((m) => m.id).join(', ')}`;
                 }
-                ctx.scrollback.push({
-                    kind: 'status',
-                    text,
-                    level: 'error',
-                    ts: Date.now(),
-                });
+                ctx.scrollback.push({ kind: 'status', text, 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(),
-                });
+            // 4. Extract client.js from already-fetched archive and install locally
+            const clientJs = readFileFromArchive(archiveBytes, 'client.js');
+            if (clientJs) {
+                const meta = buildPackageMeta(pkg, pkg.latest);
+                const result = await installPackage(clientJs, 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(),
-            });
+            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(),
-            });
+            ctx.scrollback.push({ kind: 'status', text: `install failed: ${err instanceof Error ? err.message : String(err)}`, level: 'error', ts: Date.now() });
         }
     },
 };

package/dist/artifact.d.ts

@@ -29,4 +29,6 @@ export interface ArtifactManifest {
         id: string;
         versionRange: string;
     }>;
+    /** Shard ids this app requires to be installed on the server. Written by sh3Artifact for app/combo bundles. */
+    requiredShards?: string[];
 }

package/dist/boot/satellitePayload.d.ts

@@ -8,10 +8,12 @@ export type SatellitePayload = {
         h: number;
     };
     activateShards: string[];
+    projectId?: string;
 } | {
     kind: 'app';
     appId: string;
     activateShards: string[];
+    projectId?: string;
 };
 export declare function encodePayload(payload: SatellitePayload): string;
 export declare function decodePayload(encoded: string): SatellitePayload;

package/dist/boot/satellitePayload.test.js

@@ -36,6 +36,25 @@ describe('satellite payload encode/decode', () => {
         const bad = btoa(JSON.stringify({ kind: 'mystery' }));
         expect(() => decodePayload(bad)).toThrow();
     });
+    it('round-trips a float payload with projectId', () => {
+        const payload = {
+            kind: 'float',
+            content: { type: 'slot', slotId: 's:1', viewId: 'foo:bar' },
+            size: { w: 800, h: 600 },
+            activateShards: ['foo'],
+            projectId: 'proj-abc',
+        };
+        expect(decodePayload(encodePayload(payload))).toEqual(payload);
+    });
+    it('round-trips an app payload with projectId', () => {
+        const payload = {
+            kind: 'app',
+            appId: 'sh3-store',
+            activateShards: ['sh3-core'],
+            projectId: 'proj-xyz',
+        };
+        expect(decodePayload(encodePayload(payload))).toEqual(payload);
+    });
     it('produces a URL-safe encoding (no + / =)', () => {
         // A long-ish payload increases the chance the underlying base64
         // would contain non-URL-safe characters from the standard alphabet.

package/dist/build.d.ts

@@ -70,10 +70,16 @@ export declare function composeArtifactVersion(pkgVersion: string, suffix: strin
  * 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, type) from the source
+ *   3. Extracts manifest fields (id, label, type, requiredShards) 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
  */
+/**
+ * Extract the requiredShards array from a bundled source string.
+ * Finds the first `requiredShards: [...]` array literal and parses its string IDs.
+ * Exported for testing; used internally by sh3Artifact.
+ */
+export declare function extractRequiredShardsFromBundle(bundleSource: string): string[];
 export declare function sh3Artifact(options?: Sh3ArtifactOptions): Plugin;

package/dist/build.js

@@ -19,6 +19,7 @@
 import { readFileSync, writeFileSync, unlinkSync, readdirSync, copyFileSync, existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { join } from 'node:path';
+import { createArchive } from './registry/archive.js';
 /**
  * Vite plugin that inlines extracted CSS into the JS bundle.
  *
@@ -136,12 +137,28 @@ function resolveAutoBuildSuffix() {
  * 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, type) from the source
+ *   3. Extracts manifest fields (id, label, type, requiredShards) 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
  */
+/**
+ * Extract the requiredShards array from a bundled source string.
+ * Finds the first `requiredShards: [...]` array literal and parses its string IDs.
+ * Exported for testing; used internally by sh3Artifact.
+ */
+export function extractRequiredShardsFromBundle(bundleSource) {
+    const arrayMatch = bundleSource.match(/\brequiredShards\s*:\s*\[([^\]]*)\]/);
+    if (!arrayMatch)
+        return [];
+    const ids = [];
+    const idRe = /["']([^"']+)["']/g;
+    let m;
+    while ((m = idRe.exec(arrayMatch[1])) !== null)
+        ids.push(m[1]);
+    return ids;
+}
 export function sh3Artifact(options = {}) {
     let outDir = '';
     let entryFileName = '';
@@ -238,14 +255,17 @@ export function sh3Artifact(options = {}) {
                     const m = block.match(pattern);
                     return m ? m[1] : '';
                 };
+                // Extract the requiredShards string-id array from the app manifest block.
+                const requiredShards = extractRequiredShardsFromBundle(block);
                 return {
                     id: get(/\bid\s*:\s*["']([^"']+)["']/),
                     label: get(/\blabel\s*:\s*["']([^"']+)["']/),
+                    requiredShards,
                 };
             }
             // App first, then Shard.
             const extracted = (_a = extractFromBlock(/\brequiredShards\s*:\s*\[/)) !== null && _a !== void 0 ? _a : extractFromBlock(/\bviews\s*:\s*\[/);
-            const { id, label } = extracted;
+            const { id, label, requiredShards } = extracted;
             // --- Optional server bundle ---
             let hasServer = false;
             if (options.serverEntry && existsSync(options.serverEntry)) {
@@ -292,14 +312,19 @@ 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: artifactVersion, 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'];
+            const manifest = Object.assign(Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: artifactVersion, contractVersion: 1 }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), ((type === 'app' || type === 'combo') ? { requiredShards } : {})), overrides);
+            // Read the emitted JS files as bytes for the archive
+            const clientBytes = readFileSync(join(outDir, 'client.js'));
+            const serverBytes = hasServer ? readFileSync(join(outDir, 'server.js')) : undefined;
+            // Create the .sh3pkg archive
+            const archive = createArchive(Object.assign({ manifest, client: new Uint8Array(clientBytes.buffer, clientBytes.byteOffset, clientBytes.byteLength) }, (serverBytes ? { server: new Uint8Array(serverBytes.buffer, serverBytes.byteOffset, serverBytes.byteLength) } : {})));
+            const archiveName = `${manifest.id}-${manifest.version}.sh3pkg`;
+            writeFileSync(join(outDir, archiveName), archive);
+            // Remove the loose files — the archive is the deliverable
+            unlinkSync(join(outDir, 'client.js'));
             if (hasServer)
-                files.push('server.js');
-            console.log(`[sh3-artifact] ${manifest.id}@${manifest.version} (${manifest.type}) → ${outDir}`);
-            console.log(`[sh3-artifact] files: ${files.join(', ')}`);
+                unlinkSync(join(outDir, 'server.js'));
+            console.log(`[sh3-artifact] ${manifest.id}@${manifest.version} (${manifest.type}) → ${outDir}/${archiveName}`);
         },
     };
 }

package/dist/build.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { composeArtifactVersion } from './build';
+import { composeArtifactVersion, extractRequiredShardsFromBundle } from './build';
 describe('composeArtifactVersion', () => {
     it('returns pkgVersion unchanged when suffix is undefined', () => {
         expect(composeArtifactVersion('1.2.3', undefined)).toBe('1.2.3');
@@ -29,3 +29,29 @@ describe('composeArtifactVersion', () => {
         expect(() => composeArtifactVersion('1.2.3', '+42')).toThrow(/not a valid semver build-metadata identifier/);
     });
 });
+describe('extractRequiredShardsFromBundle', () => {
+    it('extracts a single shard id', () => {
+        const src = `const App = { manifest: { id: "my-app", requiredShards: ["guml.core"] } };`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual(['guml.core']);
+    });
+    it('extracts multiple shard ids', () => {
+        const src = `requiredShards: ["guml.core", "sh3-file-explorer", "some-other"]`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual(['guml.core', 'sh3-file-explorer', 'some-other']);
+    });
+    it('handles single-quoted ids', () => {
+        const src = `requiredShards: ['guml.core', 'sh3-files']`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual(['guml.core', 'sh3-files']);
+    });
+    it('returns empty array when requiredShards is not present', () => {
+        const src = `const Shard = { manifest: { id: "my-shard", views: [] } };`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual([]);
+    });
+    it('returns empty array when requiredShards is empty', () => {
+        const src = `requiredShards: []`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual([]);
+    });
+    it('handles minified format without spaces', () => {
+        const src = `{id:"my-app",requiredShards:["guml.core","other-shard"]}`;
+        expect(extractRequiredShardsFromBundle(src)).toEqual(['guml.core', 'other-shard']);
+    });
+});