sh3-core 0.10.2 → 0.10.4

package/dist/api.d.ts

@@ -22,6 +22,8 @@ export type { BrowseCapability } from './documents/browse';
 export type { ContributionsApi } from './contributions/types';
 export type { SyncPolicy, SyncPolicyRule, DocStatus, ConflictFile, ConflictBranch, } from './documents/sync-types';
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';
+export type { ConflictItem, ConflictBranch as ConflictManagerBranch, ResolveOptions as ConflictResolveOptions, ResolveOutcome as ConflictResolveOutcome, ResolveDocumentsInput as ConflictResolveDocumentsInput, DocsResolveOutcome as ConflictDocsResolveOutcome, ConflictRenderer, ConflictRendererProps, ConflictsApi, } from './conflicts/api';
+export { CONFLICT_RENDERER_POINT, ConflictPermissionError, ConflictSessionOrphanedError, } from './conflicts/api';
 export { registeredShards, activeShards } from './shards/activate.svelte';
 export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';

package/dist/api.js

@@ -31,6 +31,7 @@ export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';
+export { CONFLICT_RENDERER_POINT, ConflictPermissionError, ConflictSessionOrphanedError, } from './conflicts/api';
 // Shard introspection — read-only reactive maps exposing which shards are
 // known to the host and which are currently active. Intended for diagnostic
 // and tooling shards that need to visualize framework state. Phase 9

package/dist/conflicts/ConflictModal.svelte

@@ -0,0 +1,131 @@
+<script lang="ts">
+  import { onDestroy } from 'svelte';
+  import type { ConflictItem, ConflictRenderer, ConflictBranch } from './api';
+  import PromptView from './PromptView.svelte';
+  import DetailView from './DetailView.svelte';
+  import { pickMostRecent } from './most-recent';
+
+  interface Props {
+    items: ConflictItem[];
+    title: string;
+    mostRecentBy: (a: ConflictBranch, b: ConflictBranch) => number;
+    requirePrompt: boolean;
+    contributed: ConflictRenderer[];
+    onResolve: (
+      choices: Array<{ itemId: string; chosen: ConflictBranch; meta?: Record<string, unknown> }>,
+      skipped: string[],
+    ) => void;
+    onCancel: () => void;
+    /** Provided by shell.modal.open wrapping; we must call to actually close. */
+    close: () => void;
+  }
+  const props: Props = $props();
+
+  type Phase = 'prompt' | 'detail';
+  // Initial values — items / requirePrompt don't change mid-session.
+  // svelte-ignore state_referenced_locally
+  const startsInPrompt = props.items.length >= 2 || props.requirePrompt;
+  let phase = $state<Phase>(startsInPrompt ? 'prompt' : 'detail');
+
+  // Initial selections: most-recent per item. Items don't change mid-session,
+  // so using the initial value here is the intended semantics.
+  // svelte-ignore state_referenced_locally
+  let selections = $state<Record<string, string>>(
+    Object.fromEntries(
+      props.items.map((it) => {
+        const pick = pickMostRecent(it.branches, props.mostRecentBy)?.origin
+          ?? it.branches[0]?.origin
+          ?? '';
+        return [it.id, pick];
+      }),
+    ),
+  );
+  let skipped = $state<Record<string, boolean>>({});
+  let currentIndex = $state(0);
+
+  // Settlement guard — the safety net in onDestroy relies on this to
+  // distinguish normal completion from unexpected dismissal (Escape,
+  // programmatic closeAll, caller-shard deactivation).
+  let settled = false;
+
+  onDestroy(() => {
+    if (!settled) {
+      settled = true;
+      props.onCancel();
+    }
+  });
+
+  function finalize(): void {
+    if (settled) return;
+    settled = true;
+    const choices: Array<{ itemId: string; chosen: ConflictBranch; meta?: Record<string, unknown> }> = [];
+    const skippedIds: string[] = [];
+    for (const it of props.items) {
+      if (skipped[it.id]) {
+        skippedIds.push(it.id);
+        continue;
+      }
+      const origin = selections[it.id];
+      const branch = it.branches.find((b) => b.origin === origin);
+      if (branch) choices.push({ itemId: it.id, chosen: branch, meta: it.meta });
+    }
+    props.onResolve(choices, skippedIds);
+    props.close();
+  }
+
+  function cancel(): void {
+    if (settled) return;
+    settled = true;
+    props.onCancel();
+    props.close();
+  }
+
+  function overwriteMostRecent(): void {
+    // Selections are already pre-filled to most-recent; finalize directly.
+    finalize();
+  }
+
+  function resolveIndividually(): void {
+    phase = 'detail';
+  }
+
+  function select(itemId: string, origin: string): void {
+    selections = { ...selections, [itemId]: origin };
+    if (skipped[itemId]) {
+      const nextSkipped = { ...skipped };
+      delete nextSkipped[itemId];
+      skipped = nextSkipped;
+    }
+  }
+
+  function toggleSkip(itemId: string): void {
+    skipped = { ...skipped, [itemId]: !skipped[itemId] };
+  }
+
+  function navigate(nextIndex: number): void {
+    currentIndex = nextIndex;
+  }
+</script>
+
+{#if phase === 'prompt'}
+  <PromptView
+    count={props.items.length}
+    onOverwriteMostRecent={overwriteMostRecent}
+    onResolveIndividually={resolveIndividually}
+    onCancel={cancel}
+  />
+{:else}
+  <DetailView
+    items={props.items}
+    {selections}
+    {skipped}
+    {currentIndex}
+    title={props.title}
+    contributed={props.contributed}
+    onSelect={select}
+    onNavigate={navigate}
+    onToggleSkip={toggleSkip}
+    onDone={finalize}
+    onCancel={cancel}
+  />
+{/if}

package/dist/conflicts/ConflictModal.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { ConflictItem, ConflictRenderer, ConflictBranch } from './api';
+interface Props {
+    items: ConflictItem[];
+    title: string;
+    mostRecentBy: (a: ConflictBranch, b: ConflictBranch) => number;
+    requirePrompt: boolean;
+    contributed: ConflictRenderer[];
+    onResolve: (choices: Array<{
+        itemId: string;
+        chosen: ConflictBranch;
+        meta?: Record<string, unknown>;
+    }>, skipped: string[]) => void;
+    onCancel: () => void;
+    /** Provided by shell.modal.open wrapping; we must call to actually close. */
+    close: () => void;
+}
+declare const ConflictModal: import("svelte").Component<Props, {}, "">;
+type ConflictModal = ReturnType<typeof ConflictModal>;
+export default ConflictModal;

package/dist/conflicts/DetailView.svelte

@@ -0,0 +1,198 @@
+<script lang="ts">
+  import type { ConflictItem, ConflictRenderer, ConflictRendererProps } from './api';
+  import { pickRenderer } from './renderer-registry';
+
+  interface Props {
+    items: ConflictItem[];
+    selections: Record<string, string>;     // itemId → chosen origin
+    skipped: Record<string, boolean>;       // itemId → true when skipped
+    currentIndex: number;
+    title: string;
+    contributed: ConflictRenderer[];
+    onSelect: (itemId: string, origin: string) => void;
+    onNavigate: (nextIndex: number) => void;
+    onToggleSkip: (itemId: string) => void;
+    onDone: () => void;
+    onCancel: () => void;
+  }
+  const props: Props = $props();
+
+  const current = $derived(props.items[props.currentIndex]);
+  const selectedOrigin = $derived(
+    current
+      ? (props.selections[current.id] ?? current.branches[0]?.origin ?? '')
+      : '',
+  );
+  const renderer = $derived(current ? pickRenderer(current, props.contributed) : null);
+
+  let rendererContainer: HTMLDivElement | undefined = $state();
+  let currentUnmount: (() => void) | null = null;
+
+  $effect(() => {
+    // Depend on current + renderer + selectedOrigin so the effect re-runs
+    // whenever any of them changes; parent-owned selection drives re-mount.
+    void current;
+    void renderer;
+    void selectedOrigin;
+    if (currentUnmount) { currentUnmount(); currentUnmount = null; }
+    if (!rendererContainer || !current || !renderer) return;
+    const rendererProps: ConflictRendererProps = {
+      item: current,
+      selectedOrigin,
+      onSelect: (origin) => props.onSelect(current.id, origin),
+    };
+    currentUnmount = renderer.mount(rendererContainer, rendererProps);
+    return () => {
+      if (currentUnmount) { currentUnmount(); currentUnmount = null; }
+    };
+  });
+
+  function prev(): void {
+    if (props.currentIndex > 0) props.onNavigate(props.currentIndex - 1);
+  }
+  function next(): void {
+    if (props.currentIndex < props.items.length - 1) props.onNavigate(props.currentIndex + 1);
+  }
+
+  const itemStates = $derived(
+    props.items.map((it) => {
+      if (props.skipped[it.id]) return 'skipped' as const;
+      if (props.selections[it.id]) return 'resolved' as const;
+      return 'pending' as const;
+    }),
+  );
+</script>
+
+<div class="sh3-conflict-detail">
+  <header class="sh3-conflict-detail-head">
+    <h3>{props.title}</h3>
+    {#if props.items.length > 1}
+      <span class="sh3-conflict-detail-counter">
+        {props.currentIndex + 1} / {props.items.length}
+      </span>
+    {/if}
+  </header>
+
+  <div class="sh3-conflict-detail-body">
+    {#if props.items.length > 1}
+      <aside class="sh3-conflict-detail-rail">
+        {#each props.items as it, i (it.id)}
+          <button
+            type="button"
+            class="sh3-conflict-detail-rail-item"
+            class:selected={i === props.currentIndex}
+            onclick={() => props.onNavigate(i)}
+          >
+            <span class="sh3-conflict-detail-rail-state {itemStates[i]}">
+              {#if itemStates[i] === 'resolved'}✓{:else if itemStates[i] === 'skipped'}⟶{:else}·{/if}
+            </span>
+            <span class="sh3-conflict-detail-rail-label">{it.label}</span>
+          </button>
+        {/each}
+      </aside>
+    {/if}
+
+    <section class="sh3-conflict-detail-main">
+      {#if current}
+        <div class="sh3-conflict-detail-branches">
+          {#each current.branches as b (b.origin)}
+            <label class="sh3-conflict-detail-branch">
+              <input
+                type="radio"
+                name="branch-{current.id}"
+                value={b.origin}
+                checked={selectedOrigin === b.origin}
+                onchange={() => props.onSelect(current.id, b.origin)}
+              />
+              <span>{b.origin} · v{b.version}</span>
+            </label>
+          {/each}
+        </div>
+        <div bind:this={rendererContainer} class="sh3-conflict-detail-renderer"></div>
+      {/if}
+    </section>
+  </div>
+
+  <footer class="sh3-conflict-detail-foot">
+    <div class="sh3-conflict-detail-nav">
+      <button type="button" onclick={prev} disabled={props.currentIndex === 0}>← Prev</button>
+      <button type="button" onclick={() => current && props.onToggleSkip(current.id)}>
+        {current && props.skipped[current.id] ? 'Unskip' : 'Skip'}
+      </button>
+      <button type="button" onclick={next} disabled={props.currentIndex >= props.items.length - 1}>
+        Next →
+      </button>
+    </div>
+    <div class="sh3-conflict-detail-actions">
+      <button type="button" class="sh3-conflict-detail-cancel" onclick={props.onCancel}>Cancel</button>
+      <button type="button" class="sh3-conflict-detail-done" onclick={props.onDone}>Done</button>
+    </div>
+  </footer>
+</div>
+
+<style>
+  .sh3-conflict-detail {
+    display: flex; flex-direction: column;
+    width: min(920px, 96vw); height: min(640px, 90vh);
+    background: var(--shell-bg, #1e1e1e);
+    color: var(--shell-fg, #e0e0e0);
+    border: 1px solid var(--shell-border, #444);
+    border-radius: var(--shell-radius-md);
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  }
+  .sh3-conflict-detail-head {
+    padding: 12px 16px; border-bottom: 1px solid var(--shell-border, #444);
+    display: flex; justify-content: space-between; align-items: center;
+  }
+  .sh3-conflict-detail-head h3 { margin: 0; font-size: 1rem; font-weight: 600; }
+  .sh3-conflict-detail-counter { color: var(--shell-fg-muted, #888); font-size: 0.8125rem; }
+  .sh3-conflict-detail-body { display: flex; flex: 1; min-height: 0; }
+  .sh3-conflict-detail-rail {
+    width: 240px; border-right: 1px solid var(--shell-border, #444);
+    overflow-y: auto; display: flex; flex-direction: column;
+  }
+  .sh3-conflict-detail-rail-item {
+    display: flex; gap: 8px; align-items: center;
+    padding: 6px 12px; text-align: left;
+    background: transparent; border: none; color: inherit;
+    cursor: pointer; font: inherit; font-size: 0.8125rem;
+  }
+  .sh3-conflict-detail-rail-item:hover { background: var(--shell-input-bg, #2a2a2a); }
+  .sh3-conflict-detail-rail-item.selected { background: var(--shell-input-bg, #2a2a2a); font-weight: 600; }
+  .sh3-conflict-detail-rail-state { width: 1em; text-align: center; opacity: 0.7; }
+  .sh3-conflict-detail-rail-state.resolved { color: var(--shell-success, #3a3); opacity: 1; }
+  .sh3-conflict-detail-rail-state.skipped { color: var(--shell-fg-muted, #888); }
+  .sh3-conflict-detail-rail-label {
+    flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+  .sh3-conflict-detail-main { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+  .sh3-conflict-detail-branches {
+    display: flex; gap: 12px; padding: 8px 16px;
+    border-bottom: 1px solid var(--shell-border, #444);
+    flex-wrap: wrap;
+  }
+  .sh3-conflict-detail-branch { display: flex; gap: 6px; align-items: center; font-size: 0.8125rem; }
+  .sh3-conflict-detail-renderer { flex: 1; min-height: 0; overflow: auto; }
+  .sh3-conflict-detail-foot {
+    padding: 10px 16px; border-top: 1px solid var(--shell-border, #444);
+    display: flex; justify-content: space-between; gap: 8px;
+  }
+  .sh3-conflict-detail-nav, .sh3-conflict-detail-actions { display: flex; gap: 8px; }
+  .sh3-conflict-detail-nav button, .sh3-conflict-detail-actions button {
+    padding: 6px 14px;
+    background: var(--shell-input-bg, #2a2a2a);
+    color: var(--shell-fg, #e0e0e0);
+    border: 1px solid var(--shell-border, #444);
+    border-radius: var(--shell-radius);
+    font: inherit;
+    font-size: 0.8125rem;
+    cursor: pointer;
+  }
+  .sh3-conflict-detail-nav button:disabled { opacity: 0.5; cursor: not-allowed; }
+  .sh3-conflict-detail-done {
+    background: var(--shell-accent, #007acc) !important;
+    color: #fff !important;
+    font-weight: 600;
+    border-color: var(--shell-accent, #007acc) !important;
+  }
+</style>

package/dist/conflicts/DetailView.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { ConflictItem, ConflictRenderer } from './api';
+interface Props {
+    items: ConflictItem[];
+    selections: Record<string, string>;
+    skipped: Record<string, boolean>;
+    currentIndex: number;
+    title: string;
+    contributed: ConflictRenderer[];
+    onSelect: (itemId: string, origin: string) => void;
+    onNavigate: (nextIndex: number) => void;
+    onToggleSkip: (itemId: string) => void;
+    onDone: () => void;
+    onCancel: () => void;
+}
+declare const DetailView: import("svelte").Component<Props, {}, "">;
+type DetailView = ReturnType<typeof DetailView>;
+export default DetailView;

package/dist/conflicts/PromptView.svelte

@@ -0,0 +1,55 @@
+<script lang="ts">
+  interface Props {
+    count: number;
+    onOverwriteMostRecent: () => void;
+    onResolveIndividually: () => void;
+    onCancel: () => void;
+  }
+  const { count, onOverwriteMostRecent, onResolveIndividually, onCancel }: Props = $props();
+</script>
+
+<div class="sh3-conflict-prompt">
+  <h3 class="sh3-conflict-prompt-title">
+    {count} conflict{count === 1 ? '' : 's'} to resolve
+  </h3>
+  <p class="sh3-conflict-prompt-intro">
+    Pick one option for the whole batch, or resolve each conflict individually.
+  </p>
+  <div class="sh3-conflict-prompt-actions">
+    <!-- svelte-ignore a11y_autofocus -->
+    <button type="button" class="sh3-conflict-prompt-primary" onclick={onOverwriteMostRecent} autofocus>
+      Overwrite with most recent
+    </button>
+    <button type="button" class="sh3-conflict-prompt-secondary" onclick={onResolveIndividually}>
+      Resolve individually
+    </button>
+    <button type="button" class="sh3-conflict-prompt-cancel" onclick={onCancel}>
+      Cancel
+    </button>
+  </div>
+</div>
+
+<style>
+  .sh3-conflict-prompt { padding: 20px; display: flex; flex-direction: column; gap: 14px; min-width: 360px; max-width: 480px; }
+  .sh3-conflict-prompt-title { margin: 0; font-size: 1.0625rem; font-weight: 600; color: var(--shell-fg, #e0e0e0); }
+  .sh3-conflict-prompt-intro { margin: 0; color: var(--shell-fg-muted, #888); font-size: 0.875rem; }
+  .sh3-conflict-prompt-actions { display: flex; flex-direction: column; gap: 8px; }
+  .sh3-conflict-prompt-actions button {
+    padding: 10px 14px;
+    border-radius: var(--shell-radius);
+    border: 1px solid var(--shell-border, #444);
+    background: var(--shell-input-bg, #2a2a2a);
+    color: var(--shell-fg, #e0e0e0);
+    font-size: 0.875rem;
+    font-family: inherit;
+    cursor: pointer;
+    text-align: left;
+  }
+  .sh3-conflict-prompt-primary {
+    background: var(--shell-accent, #007acc) !important;
+    border-color: var(--shell-accent, #007acc) !important;
+    color: #fff !important;
+    font-weight: 600;
+  }
+  .sh3-conflict-prompt-cancel { color: var(--shell-fg-muted, #888) !important; }
+</style>

package/dist/conflicts/PromptView.svelte.d.ts

@@ -0,0 +1,9 @@
+interface Props {
+    count: number;
+    onOverwriteMostRecent: () => void;
+    onResolveIndividually: () => void;
+    onCancel: () => void;
+}
+declare const PromptView: import("svelte").Component<Props, {}, "">;
+type PromptView = ReturnType<typeof PromptView>;
+export default PromptView;

package/dist/conflicts/adapter-documents.d.ts

@@ -0,0 +1,3 @@
+import type { ShardContext } from '../shards/types';
+import { type DocsResolveOutcome, type ResolveDocumentsInput, type ResolveOptions } from './api';
+export declare function resolveDocuments(ctx: ShardContext, input: ResolveDocumentsInput, opts?: ResolveOptions): Promise<DocsResolveOutcome>;

package/dist/conflicts/adapter-documents.js

@@ -0,0 +1,119 @@
+/*
+ * Doc-zone adapter for shell.conflicts.
+ *
+ * Reads DocStatus for each requested path, filters to those actually in
+ * conflict, fetches per-branch content for preview, and invokes the
+ * generic primitive. On resolve, applies each chosen branch via the
+ * appropriate handle (own-shard via ctx.documents(); cross-shard via
+ * ctx.browse.resolveConflictFrom).
+ *
+ * Cross-shard requires the caller's manifest to declare documents:browse
+ * + documents:read + documents:write — detected via the presence of the
+ * capability methods on ctx.browse. The adapter throws
+ * ConflictPermissionError when any required capability is missing.
+ *
+ * Apply step is sequential; HTTP resolveConflict races the server's
+ * per-doc tick counter when parallelized. Failure isolation: one failed
+ * resolveConflict does not stop the batch; the caller gets both lists.
+ */
+import { ConflictPermissionError, } from './api';
+import { resolvePrimitive } from './resolve-primitive';
+function ownShardHandle(ctx) {
+    // No extension filter — the adapter takes caller-supplied paths, any type.
+    const h = ctx.documents({ format: 'text' });
+    return {
+        status: (p) => h.status(p),
+        readBranch: (p, o) => h.readBranch(p, o),
+        resolveConflict: (p, c) => h.resolveConflict(p, c),
+    };
+}
+function crossShardHandle(ctx, shardId) {
+    const b = ctx.browse;
+    if (!(b === null || b === void 0 ? void 0 : b.statusFrom) || !(b === null || b === void 0 ? void 0 : b.readBranchFrom) || !(b === null || b === void 0 ? void 0 : b.resolveConflictFrom)) {
+        throw new ConflictPermissionError(`Cross-shard resolveDocuments requires documents:browse + documents:read + documents:write (shardId=${shardId})`);
+    }
+    return {
+        status: (p) => b.statusFrom(shardId, p),
+        readBranch: (p, o) => b.readBranchFrom(shardId, p, o),
+        resolveConflict: (p, c) => b.resolveConflictFrom(shardId, p, c),
+    };
+}
+function extractExtension(path) {
+    const i = path.lastIndexOf('.');
+    if (i < 0)
+        return undefined;
+    const j = path.lastIndexOf('/');
+    if (i < j)
+        return undefined; // dot is in a parent directory
+    return path.slice(i);
+}
+export async function resolveDocuments(ctx, input, opts = {}) {
+    var _a, _b;
+    const callerShardId = ctx.shardId;
+    const handle = input.shardId === callerShardId
+        ? ownShardHandle(ctx)
+        : crossShardHandle(ctx, input.shardId);
+    // Pre-filter: keep only paths actually in conflict state.
+    const statuses = [];
+    for (const path of input.paths) {
+        const s = await handle.status(path);
+        if (s && s.syncState === 'conflict' && s.branches && s.branches.length > 0) {
+            statuses.push({ path, status: s });
+        }
+    }
+    if (statuses.length === 0) {
+        return { status: 'resolved', resolved: [], failed: [], skipped: [] };
+    }
+    // Build ConflictItem[] with per-branch content fetched via readBranch.
+    const items = [];
+    for (const { path, status } of statuses) {
+        const extension = extractExtension(path);
+        const branches = [];
+        for (const b of (_a = status.branches) !== null && _a !== void 0 ? _a : []) {
+            const content = await handle.readBranch(path, b.origin).catch(() => null);
+            branches.push({
+                origin: b.origin,
+                version: b.version,
+                at: b.at,
+                content: content !== null && content !== void 0 ? content : undefined,
+                sizeBytes: content ? new TextEncoder().encode(content).length : undefined,
+            });
+        }
+        items.push({
+            id: path,
+            label: path,
+            extension,
+            branches,
+            meta: { shardId: input.shardId, path, docVersion: status.version },
+        });
+    }
+    const outcome = await resolvePrimitive(items, opts);
+    if (outcome.status === 'cancelled')
+        return { status: 'cancelled' };
+    // Apply each chosen branch sequentially.
+    const resolvedList = [];
+    const failedList = [];
+    for (const choice of outcome.choices) {
+        try {
+            await handle.resolveConflict(choice.itemId, { origin: choice.chosen.origin });
+            const after = await handle.status(choice.itemId).catch(() => null);
+            resolvedList.push({
+                path: choice.itemId,
+                chosen: choice.chosen,
+                appliedVersion: (_b = after === null || after === void 0 ? void 0 : after.version) !== null && _b !== void 0 ? _b : -1,
+            });
+        }
+        catch (err) {
+            failedList.push({
+                path: choice.itemId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return {
+        status: 'resolved',
+        resolved: resolvedList,
+        failed: failedList,
+        skipped: outcome.skipped,
+    };
+}