selfstore 1.0.0

package/dist/sync.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Hybrid Logical Clock: wall time + a counter + a node id, giving a
+ * deterministic total order that tolerates clock skew. Encoded as a fixed-width
+ * string so a plain string comparison equals causal order.
+ */
+type Hlc = string;
+/** A fresh random replica id (one per device). */
+declare function createNode(): string;
+
+/**
+ * Schema-agnostic convergent merge for plain JSON. It keeps a small sidecar of
+ * metadata (one logical clock per record) and reconciles two replica states with
+ * well-known set semantics. Documents stay plain objects: identity is a
+ * configured id field, change detection is by content hash, nothing is injected.
+ *
+ * Per-collection strategy:
+ *   'lww-set'      records keyed by id; later write per id wins; deletes tombstoned.
+ *   'lww-map'      records keyed by id, merged field BY field: concurrent edits
+ *                  to different fields of one record both survive; the same field
+ *                  goes to the later clock. Deletes stay record-level.
+ *   'grow-set'     append-only; entries immutable; union, never a conflict.
+ *   'lww-register' a single value; later write wins.
+ *   'manual'       surface concurrent edits to the same id instead of resolving.
+ *
+ * For collaborative rich text, store an Automerge/Yjs document as a binary file
+ * in the snapshot instead; this engine stops short of sequence CRDTs.
+ */
+
+type Id = string;
+type MergeStrategy = 'lww-set' | 'lww-map' | 'grow-set' | 'lww-register' | 'manual';
+interface SyncConfig {
+    /** Field holding each record's stable id (default 'id'). Dot-notation allowed. */
+    idField?: string;
+    /** Per-collection id path override for records whose id is not at the top level. */
+    ids?: Record<string, string>;
+    /** Strategy per collection name; anything unlisted uses `fallback`. */
+    strategies?: Record<string, MergeStrategy>;
+    /** Strategy for unlisted collections (default 'lww-set'). */
+    fallback?: MergeStrategy;
+}
+/** Sidecar metadata for one collection, keyed by record id. */
+interface ColMeta {
+    clocks: Record<Id, Hlc>;
+    deleted: Record<Id, Hlc>;
+    hashes: Record<Id, number>;
+    /** 'lww-map' only: per-field [clock, contentHash], so concurrent edits to
+     *  different fields of one record merge instead of one side losing. */
+    fields?: Record<Id, Record<string, [Hlc, number]>>;
+}
+/** Everything one replica tracks. Travels with the data so the other side can merge. */
+interface SyncMeta {
+    node: string;
+    clock: Hlc | null;
+    cols: Record<string, ColMeta>;
+}
+/** A same-id concurrent edit the 'manual' strategy refused to auto-resolve.
+ *  `local`/`remote` carry the two full versions during the session; consumers
+ *  persisting conflicts (e.g. the store's journal) redact them, so they are
+ *  absent after a reload - never write user records to unencrypted storage. */
+interface Conflict {
+    collection: string;
+    id: Id;
+    local?: unknown;
+    remote?: unknown;
+    /** The side kept as the provisional value (so it still converges). */
+    kept: 'local' | 'remote';
+}
+interface MergeResult {
+    collections: Record<string, unknown[]>;
+    meta: SyncMeta;
+    conflicts: Conflict[];
+}
+declare function createMeta(node?: string): SyncMeta;
+declare function stamp(meta: SyncMeta, collections: Record<string, unknown[]>, config: SyncConfig, wallNow?: number): SyncMeta;
+/** One replica's full state: the collections plus their sync metadata. What
+ *  `merge` and `detectConflicts` take on each side. */
+interface ReplicaState {
+    collections: Record<string, unknown[]>;
+    meta: SyncMeta;
+}
+type State = ReplicaState;
+/**
+ * Merge replica `b` into `a` (commutative for the convergent strategies). The
+ * optional `base` lets 'manual' tell a true concurrent conflict from a one-sided
+ * change; without it, 'manual' errs toward surfacing.
+ */
+declare function merge(a: State, b: State, config: SyncConfig, base?: SyncMeta): MergeResult;
+/**
+ * Concurrent same-id edits that a convergent strategy resolves silently by keeping
+ * the later clock. Informational only: it never changes what `merge` keeps, it
+ * reports which records both replicas changed since `base` (the loser's version is
+ * the one merge dropped). Empty without a base, since two-way state alone cannot
+ * tell a concurrent edit from a one-sided change.
+ */
+declare function detectConflicts(a: State, b: State, config: SyncConfig, base?: SyncMeta): Conflict[];
+/** What a merge did to one collection, counted by record. */
+interface CollectionChanges {
+    added: number;
+    updated: number;
+    removed: number;
+}
+/** Per-collection record counts of what changed between two states (same id
+ *  resolution as the merge). Collections with no change are omitted, so an empty
+ *  result means the states are equivalent. Feeds the sync journal. */
+declare function changes(before: Record<string, unknown[]>, after: Record<string, unknown[]>, config: SyncConfig): Record<string, CollectionChanges>;
+
+export { type ColMeta, type CollectionChanges, type Conflict, type Hlc, type Id, type MergeResult, type MergeStrategy, type ReplicaState, type SyncConfig, type SyncMeta, changes, createMeta, createNode, detectConflicts, merge, stamp };

package/dist/sync.js

@@ -0,0 +1,3 @@
+export { changes, createMeta, createNode, detectConflicts, merge, stamp } from './chunk-IBIEKK36.js';
+//# sourceMappingURL=sync.js.map
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sync.js"}

package/dist/widgets.d.ts

@@ -0,0 +1,426 @@
+import { FlowHost, ConnectTargets, ConnectFlowOptions, ConnectKind, ConnectFlow, ShareEngine, ShareLevel, ShareFlow, JoinEngine, JoinFlow, ReplicaFlow } from './flows.js';
+import { BackupsManager } from './backups.js';
+import './store-ChIGEOph.js';
+import './cache-De5_sALA.js';
+import './sync.js';
+import './drive-Bv94UM8b.js';
+import './machine-ALMkT3mk.js';
+
+/** Flat key -> string map; widgets merge a partial override over EN defaults. */
+type WidgetLabels = Record<string, string>;
+/** The common shell: shadow root + styles, label merging, focus-preserving
+ *  re-render, event emission, subscription cleanup. */
+declare abstract class FlowWidget extends HTMLElement {
+    protected root: ShadowRoot;
+    private styleEl;
+    private body;
+    private overrides;
+    protected unsub: (() => void) | null;
+    /** The widget's EN default strings; subclasses provide theirs. */
+    protected abstract defaults(): WidgetLabels;
+    /** Build the current view into the given container. */
+    protected abstract view(into: HTMLElement): void;
+    constructor();
+    /** Partial override map, merged over the EN defaults (also the i18n hook). */
+    get labels(): WidgetLabels;
+    set labels(map: WidgetLabels);
+    protected t(key: string): string;
+    /** A heading an empty-string label removes: labels = { 'share.title': '' }
+     *  hides that heading (the host page already says it) without a fork.
+     *  Append through put(), which skips the null. */
+    protected heading(part: string, key: string): HTMLElement | null;
+    /** Map a flow error to copy: labels can override per labelKey
+     *  ('error.targetUnavailable', ...), with a generic fallback. */
+    protected errorText(labelKey: string | undefined): string;
+    protected emit(name: string, detail?: unknown): void;
+    /** Rebuild the body, keeping the focused input's value and focus across the
+     *  rebuild (inputs carry data-keep so typing survives a snapshot change). */
+    protected rerender(): void;
+    disconnectedCallback(): void;
+}
+
+/**
+ * <selfstore-connect>: the "where does my data live" journey, ready to drop
+ * in. A thin skin over connectFlow - every ordering and failure rule lives in
+ * the flow (and its tests); this element only renders the snapshot and calls
+ * the actions. Theme it with --selfstore-* custom properties and ::part()
+ * selectors; reword or localize it through the `labels` property.
+ *
+ *   import { defineSelfstoreWidgets } from 'selfstore/widgets';
+ *   defineSelfstoreWidgets();
+ *
+ *   const el = document.querySelector('selfstore-connect');
+ *   el.store = store;                                  // simple store (or a FlowHost)
+ *   el.targets = { drive: gisDriveAuth({ clientId }), file: true };
+ *   el.addEventListener('selfstore-connected', (e) => ...e.detail.outcome...);
+ */
+
+/** A named WebDAV provider offered in the connect form's quick-pick row, so a
+ *  user can start from their host instead of a blank URL field. selfstore ships
+ *  no list - the app supplies whichever providers it wants to surface (its own
+ *  server, a sovereign host, ...); the widget just renders them and pre-fills the
+ *  URL field on pick. Pure UI sugar over the same WebDAV form. */
+interface WebdavPreset {
+    /** Stable id (also the `data-preset` attribute, for theming/tests). */
+    id: string;
+    /** Button text: the provider or host name. */
+    label: string;
+    /** Base server URL that pre-fills the WebDAV URL field when picked. Omit for a
+     *  label-only entry (the user then types the full URL themselves). */
+    url?: string;
+    /** Optional guidance, shown as a line under the form once this preset is
+     *  picked (e.g. where to find the app password for this host) and as the
+     *  quick-pick button's tooltip. */
+    help?: string;
+    /** Optional link appended to the `help` line (e.g. a how-to page). */
+    helpUrl?: string;
+    /** Optional "create an account" link shown once this preset is picked, for a
+     *  user who has no account with the host yet. The app owns the URL; selfstore
+     *  hard-codes no provider. */
+    signupUrl?: string;
+}
+declare class SelfstoreConnectElement extends FlowWidget {
+    #private;
+    static get observedAttributes(): string[];
+    protected defaults(): WidgetLabels;
+    /** The simple store (anything exposing `flowHost`), or a hand-built FlowHost. */
+    get store(): FlowHost | {
+        flowHost: FlowHost;
+    } | null;
+    set store(v: FlowHost | {
+        flowHost: FlowHost;
+    } | null);
+    get targets(): ConnectTargets | null;
+    set targets(v: ConnectTargets | null);
+    get options(): ConnectFlowOptions;
+    set options(v: ConnectFlowOptions);
+    /** Badge one destination as the one to pick (part="tag", label
+     *  'connect.recommended'). Purely a highlight: the order still follows the
+     *  targets object. Also the `recommended` attribute. Default: none. */
+    get recommended(): ConnectKind | null;
+    set recommended(v: ConnectKind | null);
+    /** An optional icon per destination - an image URL or data URI, rendered as
+     *  part="icon" at the head of that card. Purely decorative and per-instance;
+     *  omit a kind for no icon. Size it with --selfstore-icon-size. */
+    get icons(): Partial<Record<ConnectKind, string>>;
+    set icons(v: Partial<Record<ConnectKind, string>> | null);
+    /** Destinations to tuck behind a discreet link under the cards instead of a
+     *  full card - for power-user options (say, WebDAV) that must stay reachable
+     *  without weighing the everyday choice. Also the `advanced` attribute
+     *  (comma-separated). The journey after the click is exactly the same. */
+    get advanced(): ConnectKind[];
+    set advanced(v: ConnectKind[] | null);
+    /** Named WebDAV providers offered as a quick-pick row above the WebDAV form,
+     *  pre-filling the URL field. The app owns the list (its own host, sovereign
+     *  providers, ...); selfstore ships none. Purely additive - the blank form
+     *  still works. */
+    get webdavPresets(): WebdavPreset[];
+    set webdavPresets(v: WebdavPreset[] | null);
+    /** The underlying flow, for programmatic control (may be null until wired). */
+    get flow(): ConnectFlow | null;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    connectedCallback(): void;
+    private wire;
+    protected view(into: HTMLElement): void;
+    private destCard;
+    /** The grouped "your own server" card shown when both WebDAV and S3 are
+     *  offered: one entry into the tabbed form, opening on the first server kind. */
+    private serverCard;
+    /** WebDAV/S3 segmented toggle. Switching leaves the form and re-enters it on
+     *  the other kind - no flow surgery - and the typed fields live on the element,
+     *  so nothing the user wrote is lost across the switch. */
+    private serverTabs;
+    private webdavFormChildren;
+    private s3FormChildren;
+    private submitS3;
+    private cancel;
+    private submitPassword;
+    /** Flip the password field between hidden and shown IN PLACE - swap the
+     *  input type and the eye glyph without a re-render, so what the user has
+     *  already typed survives the toggle. */
+    private togglePassword;
+    /** Enter or leave the forgotten-password confirmation sub-state. */
+    private setConfirmOverwrite;
+    /** Confirmed: abandon the forgotten password and start a fresh backup over
+     *  the protected one (the flow makes this device win). */
+    private doOverwrite;
+    /** Fill the WebDAV URL field from a picked provider preset and move focus on to
+     *  the username, so the pick just seeds the form the user then completes. The
+     *  pick is remembered so its guidance / sign-up link render and its chip flags
+     *  as active; a re-render keeps the already-typed username and password. */
+    private pickWebdavPreset;
+    private submitWebdav;
+}
+
+/** A destructive action, offered to confirmAction before it runs: a row's
+ *  revoke/remove, or 'stop' - ending the whole share. */
+type ShareAction = {
+    type: 'revoke' | 'remove';
+    id: string;
+} | {
+    type: 'stop';
+};
+declare class SelfstoreShareElement extends FlowWidget {
+    #private;
+    static get observedAttributes(): string[];
+    protected defaults(): WidgetLabels;
+    /** The app-side transport of links and memberships (see ShareEngine). */
+    get engine(): ShareEngine | null;
+    set engine(v: ShareEngine | null);
+    /** Flow options (deadlineMs), for engines whose legs outgrow the default
+     *  30s guard (a large first upload, a slow relay). */
+    get options(): {
+        deadlineMs?: number;
+    };
+    set options(v: {
+        deadlineMs?: number;
+    } | null);
+    /** Which levels the panel OFFERS to create (['read', 'write'] by default) -
+     *  one create button per level without a live link. Also the `levels`
+     *  attribute, comma-separated: levels="read". Links the engine lists
+     *  render whatever this says. */
+    get levels(): ShareLevel[];
+    set levels(v: ShareLevel[]);
+    /** Render the create buttons (default). `with-create="off"` hides them: the
+     *  panel becomes list-and-revoke only. */
+    get withCreate(): boolean;
+    set withCreate(v: boolean);
+    /** Render the members section (default). `with-members="off"` hides it:
+     *  a links-only panel. */
+    get withMembers(): boolean;
+    set withMembers(v: boolean);
+    /** Host veto over the destructive actions: called before revoke, remove or
+     *  stop runs; answer (or resolve) false to keep things as they are -
+     *  window.confirm fits as-is. Default: everything proceeds. */
+    get confirmAction(): ((action: ShareAction) => boolean | Promise<boolean>) | null;
+    set confirmAction(v: ((action: ShareAction) => boolean | Promise<boolean>) | null);
+    /** Turn a link URL into an image source (a data URL fits): when set, each
+     *  link card renders it as an img part="qr". Injected so the element ships
+     *  no QR dependency. */
+    get qrProvider(): ((url: string) => Promise<string>) | null;
+    set qrProvider(v: ((url: string) => Promise<string>) | null);
+    get flow(): ShareFlow | null;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    connectedCallback(): void;
+    private wire;
+    protected view(into: HTMLElement): void;
+    private create;
+    /** Run a destructive action through the host's veto (default: proceed).
+     *  A throwing hook reads as "no": destruction needs a clear yes. */
+    private guarded;
+    private revoke;
+    private removeRow;
+    private stop;
+    private qrFor;
+    private copy;
+}
+
+/**
+ * <selfstore-join>: opening an invitation link, ready to drop in. A skin over
+ * joinFlow: preview first, join on an explicit yes, named outcomes (already
+ * following another share / invite spent) instead of generic errors, and the
+ * account switch as part of the journey when the engine offers one.
+ *
+ *   el.link = location.href;   // or the link attribute
+ *   el.engine = myJoinEngine;
+ *   el.addEventListener('selfstore-joined', () => goHome());
+ *
+ * variant="banner" collapses the invitation card to a one-line row (label,
+ * join, account switch) for pages that render their own preview around it.
+ */
+
+declare class SelfstoreJoinElement extends FlowWidget {
+    #private;
+    static get observedAttributes(): string[];
+    protected defaults(): WidgetLabels;
+    get engine(): JoinEngine | null;
+    set engine(v: JoinEngine | null);
+    /** The invitation. Also settable as the `link` attribute. */
+    get link(): string | null;
+    set link(v: string | null);
+    /** Flow options (deadlineMs). Set it when the engine's join opens a popup:
+     *  a generous deadline keeps the network guard without timing out a human
+     *  who is reading an account chooser. */
+    get options(): {
+        deadlineMs?: number;
+    };
+    set options(v: {
+        deadlineMs?: number;
+    } | null);
+    /** 'card' (default): the full invitation card - who shared, what level.
+     *  'banner': one line - label, join, account switch - for a host page that
+     *  renders its own preview around the widget. Also the `variant` attribute. */
+    get variant(): 'card' | 'banner';
+    set variant(v: 'card' | 'banner');
+    get flow(): JoinFlow | null;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    connectedCallback(): void;
+    private wire;
+    protected view(into: HTMLElement): void;
+}
+
+declare class SelfstoreStatusElement extends FlowWidget {
+    #private;
+    static get observedAttributes(): string[];
+    protected defaults(): WidgetLabels;
+    /** The simple store (anything exposing `flowHost`), or a hand-built FlowHost. */
+    get store(): FlowHost | {
+        flowHost: FlowHost;
+    } | null;
+    set store(v: FlowHost | {
+        flowHost: FlowHost;
+    } | null);
+    /** 'row' (dot + text + action) or 'dot' (the dot alone). Also the attribute. */
+    get variant(): 'row' | 'dot';
+    set variant(v: 'row' | 'dot' | null);
+    /** Optional icon per target kind (e.g. { drive: url, file: url }), shown
+     *  before the text in the row variant. Same contract as the connect cards. */
+    get icons(): Record<string, string>;
+    set icons(v: Record<string, string> | null);
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    connectedCallback(): void;
+    private host;
+    private wire;
+    protected view(into: HTMLElement): void;
+}
+
+/** A destructive gesture, offered to confirmAction before it runs. `delete`
+ *  and `forget` carry the row; `leave` is a membership's removal (fileId =
+ *  its wallet, null for a legacy unbound one) - the host performs the actual
+ *  leave on the 'selfstore-backups-leave' event, whose detail repeats it. */
+type BackupsAction = {
+    type: 'delete';
+    fileId: string;
+    name: string;
+    active: boolean;
+} | {
+    type: 'forget';
+    fileId: string;
+    who: string;
+} | {
+    type: 'leave';
+    fileId: string | null;
+    who: string;
+} | {
+    type: 'replica-remove';
+    label: string;
+};
+declare class SelfstoreBackupsElement extends FlowWidget {
+    #private;
+    static get observedAttributes(): string[];
+    protected defaults(): WidgetLabels;
+    /** The headless manager this panel drives (see 'selfstore/backups'). */
+    get manager(): BackupsManager | null;
+    set manager(v: BackupsManager | null);
+    /** The households this device is a member of (one entry per share, or a
+     *  single object for one): each renders in "Shared with me" labeled by who
+     *  shares it, removal = leaving (host performs it on
+     *  'selfstore-backups-leave', whose detail names the entry's fileId). With
+     *  `fileId` (the share's dedicated wallet), that registry row IS the
+     *  member row: active it wears the badge, inactive it opens like any
+     *  shared silo - and its one menu action is leaving, never a mere forget. */
+    get member(): {
+        by: string;
+        fileId?: string | null;
+    }[] | null;
+    set member(v: {
+        by: string;
+        fileId?: string | null;
+    }[] | {
+        by: string;
+        fileId?: string | null;
+    } | null);
+    /** Live state of the ATTACHED backup, from the host's store: the active
+     *  row's pills prefer these over the learned memories (which may lag). */
+    get activeEncrypted(): boolean | null;
+    set activeEncrypted(v: boolean | null);
+    get activeShared(): boolean | null;
+    set activeShared(v: boolean | null);
+    /** Host veto over the destructive gestures (delete / forget / leave):
+     *  answer (or resolve) false to keep things as they are - window.confirm
+     *  fits as-is. Default: everything proceeds. */
+    get confirmAction(): ((action: BackupsAction) => boolean | Promise<boolean>) | null;
+    set confirmAction(v: ((action: BackupsAction) => boolean | Promise<boolean>) | null);
+    get withCreate(): boolean;
+    set withCreate(v: boolean);
+    get withRename(): boolean;
+    set withRename(v: boolean);
+    get withDelete(): boolean;
+    set withDelete(v: boolean);
+    get withOpen(): boolean;
+    set withOpen(v: boolean);
+    get withEncrypt(): boolean;
+    set withEncrypt(v: boolean);
+    get withShare(): boolean;
+    set withShare(v: boolean);
+    get withShared(): boolean;
+    set withShared(v: boolean);
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    connectedCallback(): void;
+    /** Re-list the rows from the destination (the host calls this after a
+     *  gesture of its own moved things - a leave, an external change). */
+    refresh(): void;
+    private wire;
+    /** The backup-copy journey (see 'selfstore/flows' replicaFlow). Setting it
+     *  adds a menu entry on the active backup's card and renders the copy
+     *  cards under it; without it the panel is byte-identical to before. The
+     *  widget restores a recorded copy by itself. */
+    get replica(): ReplicaFlow | null;
+    set replica(v: ReplicaFlow | null);
+    /** One destination listing, then the lazy encryption probes (each learned
+     *  bit repaints its row). A transient failure keeps the last good list. */
+    private loadRows;
+    /** t() with {placeholders}. */
+    private ts;
+    private label;
+    protected view(into: HTMLElement): void;
+    private pills;
+    private rowCard;
+    private passwordCard;
+    private renameCard;
+    private createCard;
+    /** The transient setup UI under the active card: the destination choice or a
+     *  config form. The ATTACHED copy is not here - it rides inside the active
+     *  card (replicaAttachedLine). Idle renders nothing - the entry point lives
+     *  in the active card's menu. */
+    private replicaSetup;
+    /** The attached copy is not a backup of its own: it renders as ONE line
+     *  INSIDE the active backup's card, under its pills (label, freshness, an
+     *  inline "remove") - never a card or a block of its own. Null when no copy
+     *  is attached. */
+    private replicaAttachedLine;
+    private replicaPicker;
+    /** A config field: mutates state on input, no repaint (validated on submit). */
+    private replicaField;
+    private replicaWebdavForm;
+    private replicaS3Form;
+    private menuButton;
+    /** The open overflow menu: a backdrop closes it on any outside click or
+     *  tap, Escape closes it and hands focus back to its trigger. The panel is
+     *  a dropdown over the trigger's corner on wide screens and a bottom sheet
+     *  on phones - both styled in the base sheet. */
+    private menu;
+    private menuItem;
+    private eye;
+    private nameTaken;
+    /** Run a destructive action through the host's veto (default: proceed).
+     *  A throwing hook reads as "no": destruction needs a clear yes. */
+    private guarded;
+    /** Open a row programmatically - the same gesture as tapping it, password
+     *  card included. Lets a host chain "open this backup, then act on it"
+     *  (its own sub-views) without re-implementing the passphrase step. */
+    open(fileId: string, passphrase?: string): Promise<void>;
+    private create;
+    private rename;
+    private deleteRow;
+    private forget;
+    private closePw;
+}
+
+/** Register the elements as <PREFIX-connect>, <PREFIX-share>, <PREFIX-join>,
+ *  <PREFIX-status> and <PREFIX-backups> (default prefix 'selfstore'). Safe to
+ *  call twice; throws in environments without custom elements (browser code
+ *  only). */
+declare function defineSelfstoreWidgets(prefix?: string): void;
+
+export { type BackupsAction, FlowWidget, SelfstoreBackupsElement, SelfstoreConnectElement, SelfstoreJoinElement, SelfstoreShareElement, SelfstoreStatusElement, type ShareAction, type WebdavPreset, type WidgetLabels, defineSelfstoreWidgets };