@businessmaps/metaontology-nuxt 0.63.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Business Maps
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,430 @@
+# @businessmaps/metaontology-nuxt
+
+Vue 3 / Nuxt 4 integration layer for `@businessmaps/metaontology`. Provides reactive composables for commit-sourced persistence, cloud sync, cross-tab coordination, and a reactive triple store.
+
+`@businessmaps/metaontology` is a pure TypeScript package. It has no opinion about where your state lives, how it's persisted, or how mutations flow through a UI framework. That's deliberate - it keeps the engine testable and portable. But if you're building a browser application with Vue and Nuxt, you need the glue: reactive state, IndexedDB persistence, undo/redo session management, cross-tab coordination, and sync. Writing that glue correctly means handling debounced flushing, unload safety, checkpoint-and-replay loading, three-way merge on pull, echo prevention across tabs, and exponential backoff on network failures.
+
+This package is that glue. It wraps the pure engine in six composables that are auto-imported by Nuxt's layer convention, so consumers get reactive commit-sourced persistence and sync without writing any of the plumbing themselves. State is singleton per tab (module-level, not per-component), IndexedDB connection ownership lives here (one upgrade callback per database), and sync is transport-agnostic - the package defines the `SyncAdapter` interface, consumers provide implementations.
+
+```ts
+import { useModelStore, createTripleIndex } from '@businessmaps/metaontology-nuxt'
+
+const store = useModelStore()
+
+// Load a map from IndexedDB (checkpoint + replay)
+const model = await store.loadModel('my-map')
+
+// Create a reactive triple index
+const triples = createTripleIndex(() => store.root!)
+
+// O(1) lookup: what type is this entity?
+triples.entityType('thing-order')  // 'Thing'
+
+// All entities linked by 'performs'
+triples.byPredicate('performs')    // Triple[]
+```
+
+---
+
+## Getting started
+
+```bash
+npm install @businessmaps/metaontology-nuxt
+```
+
+### 1. Extend the layer
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@businessmaps/metaontology-nuxt'],
+})
+```
+
+Composables in the layer's `composables/` directory are auto-imported by Nuxt. No manual registration needed.
+
+### 2. Wire the store
+
+```ts
+// composables/useMyStore.ts
+import { useModelStore, createTripleIndex } from '@businessmaps/metaontology-nuxt'
+import { applyCommand, computeInverse } from '@businessmaps/metaontology/engine'
+import type { RootContext } from '@businessmaps/metaontology/types/context'
+
+export function useMyStore() {
+  const modelStore = useModelStore()
+  const commitLog = modelStore.commitLog
+
+  // Reactive triple index over the current model
+  const tripleIndex = createTripleIndex(() => modelStore.root!)
+
+  function dispatch(cmd) {
+    const before = modelStore.root!
+    const result = applyCommand(before, cmd)
+    if (!result.success) return result
+
+    modelStore.root = result.state
+    const inverse = computeInverse(cmd, before, result.state)
+    commitLog.appendCommit(cmd, inverse)
+
+    return result
+  }
+
+  return { root: modelStore.root, tripleIndex, dispatch }
+}
+```
+
+### 3. Explicit imports (non-Nuxt)
+
+For tools and scripts that don't run inside Nuxt, import directly:
+
+```ts
+import { useCommitLog } from '@businessmaps/metaontology-nuxt/composables/useCommitLog'
+import { createTripleIndex } from '@businessmaps/metaontology-nuxt/composables/useTripleStore'
+```
+
+The barrel `index.ts` re-exports everything from `@businessmaps/metaontology` plus all composables, so a single import source covers both packages:
+
+```ts
+import { defineThing, useModelStore, createTripleIndex }
+  from '@businessmaps/metaontology-nuxt'
+```
+
+---
+
+## Composables
+
+All composables are singletons per JavaScript context (per browser tab). Multiple call sites see the same state. Cross-tab isolation comes from the module being loaded separately in each tab, not from per-call instantiation.
+
+### useCommitLog
+
+Append-only commit log with undo/redo, checkpoint-and-replay loading, and unload safety.
+
+```ts
+const commitLog = useCommitLog()
+
+// Append a commit (command + its computed inverse)
+commitLog.appendCommit(command, inverse)
+
+// Undo: pop the inverse command, dispatch it
+const entry = commitLog.popUndo()
+if (entry) dispatch(entry.inverseCommand)
+
+// Redo: pop the original command, re-dispatch it
+const redo = commitLog.popRedo()
+if (redo) dispatch(redo.originalCommand)
+
+// Load from IndexedDB: latest checkpoint + replay commits since
+const result = await commitLog.loadFromStorage('my-map', 'main')
+// result: { model, m0, replayFailures }
+
+// Initialize a new map with a genesis checkpoint
+await commitLog.initFromSnapshot('new-map', emptyRootContext)
+
+// Subscribe to commit appends (for cross-tab broadcast, telemetry, etc.)
+const unbind = commitLog.onAppend((commit) => {
+  console.log('committed:', commit.id, commit.command.type)
+})
+```
+
+Key behaviors:
+- Debounced flush to IndexedDB (800ms after last append)
+- Cap-triggered flush when the pending buffer exceeds 25 commits (prevents debounce starvation during rapid AI tool calls)
+- Automatic checkpointing every 100 commits
+- Unload safety via `visibilitychange`, `pagehide`, and `beforeunload` handlers
+- Session undo/redo stacks (max 50 entries, reset on page reload)
+- Schema migration runs on the checkpoint at load time, not inside `applyCommand`
+
+### useSyncEngine
+
+Cloud sync state machine with debounced push, pull with fast-forward or three-way merge, and exponential backoff.
+
+```ts
+const sync = useSyncEngine()
+
+// Activate with an adapter and a host
+sync.activate(adapter, {
+  getRoot: () => store.root,
+  applyFastForward: (commits) => { /* replay remote commits */ },
+  applyMerged: (mergedModel) => { /* install merged model */ },
+  onConflict: (result) => { /* surface conflicts for resolution */ },
+})
+
+// Schedule a push after the 5s debounce
+sync.schedulePush()
+
+// Manual push/pull
+await sync.push()
+await sync.pull()
+
+// Full cycle: pull then push
+await sync.sync()
+
+// Read-only reactive state
+sync.status.value      // 'idle' | 'pushing' | 'pulling' | 'conflict' | 'error'
+sync.pendingCount.value // number of unsynced commits
+sync.lastError.value   // friendly error message or null
+sync.enabled.value     // true if activated
+
+// Restore persisted sync cursor on page load
+await sync.primeCursor('my-map', 'main')
+
+// Deactivate
+sync.deactivate()
+```
+
+Key behaviors:
+- 5-second debounce on push (coalesces rapid edits)
+- Exponential backoff on failure (5s base, 60s cap, max 5 retries)
+- Error classification: `network`, `cors`, `auth`, `conflict`, `server`, `crypto`, `unknown`
+- Console log throttling (one line per error category per retry cycle)
+- Pull handles two cases: fast-forward (no local divergence) or three-way merge (local and remote diverged)
+- Push filter support for cross-tab dedup (set by `useCrossTab`)
+- Sync cursor persisted to IDB so page refresh doesn't re-push already-synced commits
+
+### createTripleIndex
+
+Vue `computed()` wrapper around the pure triple projection. Rebuilds reactively when the model changes.
+
+```ts
+import { createTripleIndex } from '@businessmaps/metaontology-nuxt'
+
+const index = createTripleIndex(
+  () => store.root,      // reactive model accessor
+  () => store.m0State,   // optional M0 state for cross-tier triples
+)
+
+// O(1) lookups
+index.bySubject('thing-order')             // all triples about this entity
+index.byPredicate('performs')              // all 'performs' relationships
+index.bySP('persona-1', 'performs')        // what does persona-1 perform?
+index.byPO('performs', 'action-checkout')  // who performs the checkout action?
+index.has('p1', 'performs', 'a1')          // existence check
+
+// Convenience helpers
+index.objectIds('persona-1', 'performs')   // string[] of target entity IDs
+index.subjectIds('action-1', 'performs')   // string[] of source entity IDs
+index.firstObjectId('p1', 'owns')          // string | undefined (1:1 relationships)
+index.entityType('thing-order')            // 'Thing' | 'Persona' | ...
+```
+
+This is a factory, not a singleton. Each call creates a new reactive index bound to the provided accessor. Use one per store.
+
+### useModelStore
+
+High-level CRUD over maps in IndexedDB. Wraps `useCommitLog` with load, save, list, and delete operations.
+
+```ts
+const store = useModelStore()
+
+// Load a map (checkpoint + replay)
+const model = await store.loadModel('my-map', 'main')
+
+// Save a new map (genesis checkpoint)
+await store.saveModel(newRootContext)
+
+// List all persisted map IDs
+const mapIds = await store.listMaps()
+
+// Delete a map and all its commits, checkpoints, and branch heads
+await store.deleteMap('old-map')
+
+// Reactive state
+store.root.value         // RootContext | null
+store.isLoaded.value     // boolean
+store.loading.value      // boolean
+store.currentMapId.value // string
+store.error.value        // string | null
+
+// Access the underlying commit log for advanced operations
+store.commitLog.canUndo.value  // boolean
+```
+
+### useCrossTab
+
+BroadcastChannel-based cross-tab commit relay. When two browser tabs have the same map open, edits in one tab appear in the other without a server round-trip.
+
+```ts
+const crossTab = useCrossTab()
+
+// Activate for a map with a host that handles incoming commits
+crossTab.activate('my-map', {
+  applyRemoteCommit: (commit) => {
+    // Apply the command to local model state.
+    // Must NOT call appendCommit (which would re-broadcast).
+  },
+})
+
+// Per-tab identity (stable for the life of this tab)
+crossTab.getTabId()  // string
+
+// Check if a commit was received from another tab
+crossTab.wasReceivedFromAnotherTab(commitId)  // boolean
+
+// Deactivate (closes the BroadcastChannel)
+crossTab.deactivate()
+```
+
+Key behaviors:
+- Per-tab identity via `nanoid()` for echo prevention
+- Automatic push filter installation on `useSyncEngine` so commits received cross-tab are not re-pushed to the cloud by this tab
+- Idempotent receive (duplicate commit IDs are dropped)
+- Graceful degradation when `BroadcastChannel` is unavailable (non-browser environments)
+
+### syncTypes
+
+Types and utilities for the sync adapter contract. Not a composable, but auto-imported alongside the composables.
+
+```ts
+import type { SyncAdapter, SyncStatus, SyncErrorCategory,
+  PushResult, PullResult, SyncTargetDescriptor } from '@businessmaps/metaontology-nuxt'
+import { classifySyncError, friendlySyncErrorMessage } from '@businessmaps/metaontology-nuxt'
+
+// Classify any thrown error
+classifySyncError(new Error('Failed to fetch'))  // 'network'
+classifySyncError({ statusCode: 401 })           // 'auth'
+classifySyncError({ statusCode: 409 })           // 'conflict'
+
+// User-facing message
+friendlySyncErrorMessage('network')  // 'Cloud unreachable - working locally'
+friendlySyncErrorMessage('auth')     // 'Sign-in expired'
+```
+
+---
+
+## IDB schema
+
+The layer owns the IndexedDB connection (because IDB only allows one upgrade callback per database version). The schema defines 11 stores in a single `businessmaps` database:
+
+**Model-tier (layer-owned, fully typed):**
+
+| Store | Key | Indexes | Purpose |
+|---|---|---|---|
+| `commits` | `id` | `by-map-branch-seq` | Append-only command log |
+| `checkpoints` | `id` | `by-map-branch-seq` | Periodic model snapshots |
+| `heads` | `[mapId, branchId]` | - | Branch pointers |
+
+**Legacy / canvas-tier (app-owned, typed as `unknown` at the layer):**
+
+`documents`, `branches`, `history`, `config`, `tabs`, `conversations`, `blobs`, `sync_queue`
+
+The layer creates all stores in the upgrade callback but only reads/writes the model-tier stores. App code accesses the same connection via a thin proxy that re-exports `getDb` and `closeDb`.
+
+---
+
+## Implementing a SyncAdapter
+
+The `SyncAdapter` interface is transport-agnostic. The sync engine calls `push`, `pull`, and `getRemoteHead` without knowing whether commits travel over HTTP, WebSocket, filesystem, or carrier pigeon.
+
+```ts
+import type { SyncAdapter, PushResult, PullResult } from '@businessmaps/metaontology-nuxt'
+import type { Commit } from '@businessmaps/metaontology/types/commits'
+
+class MyCloudAdapter implements SyncAdapter {
+  readonly descriptor = {
+    kind: 'cloud' as const,
+    label: 'My Cloud',
+    icon: 'cloud' as const,
+  }
+
+  async push(
+    mapId: string,
+    branchId: string,
+    commits: Commit[],
+    baseSequence: number,
+  ): Promise<PushResult> {
+    // Upload commits to your backend.
+    // Return { success: true, newHeadSequence } on success.
+    // Return { success: false, conflict: true } on 409.
+    const res = await fetch(`/api/sync/${mapId}/${branchId}`, {
+      method: 'POST',
+      body: JSON.stringify({ commits, baseSequence }),
+    })
+
+    if (res.status === 409) {
+      return { success: false, newHeadSequence: baseSequence, conflict: true }
+    }
+
+    const data = await res.json()
+    return { success: true, newHeadSequence: data.headSequence }
+  }
+
+  async pull(
+    mapId: string,
+    branchId: string,
+    sinceSequence: number,
+  ): Promise<PullResult> {
+    // Fetch commits since a given sequence.
+    const res = await fetch(
+      `/api/sync/${mapId}/${branchId}?since=${sinceSequence}`,
+    )
+    const data = await res.json()
+    return {
+      success: true,
+      commits: data.commits,
+      remoteHead: data.headSequence,
+    }
+  }
+
+  async getRemoteHead(mapId: string, branchId: string): Promise<number> {
+    const res = await fetch(`/api/sync/${mapId}/${branchId}/head`)
+    const data = await res.json()
+    return data.headSequence
+  }
+}
+```
+
+Pass the adapter to `useSyncEngine().activate(adapter, host)`. The engine handles debouncing, retries, merge, and error classification. The adapter handles transport.
+
+---
+
+## Dependency injection seams
+
+Two host interfaces keep the layer from importing app code:
+
+**`SyncHost`** (used by `useSyncEngine`): the app provides `getRoot()`, `applyFastForward(commits)`, `applyMerged(model)`, and `onConflict(result)`. The engine drives sync state and retries; it delegates side effects to the host.
+
+**`CrossTabHost`** (used by `useCrossTab`): the app provides `applyRemoteCommit(commit)`. When a commit arrives from another tab, the composable calls the host. The host applies the command to its local model state without re-broadcasting or re-pushing.
+
+This pattern means the layer never imports from `app/` or `layers/bm/`. The app implements the interfaces and passes instances during activation. The boundary is enforced by `eslint-plugin-boundaries`.
+
+---
+
+## Directory structure
+
+```
+composables/
+  useCommitLog.ts       Append-only commit log, undo/redo, checkpoint/replay
+  useSyncEngine.ts      Cloud sync state machine, merge, retry
+  useTripleStore.ts     Reactive triple index (Vue computed wrapper)
+  useModelStore.ts      High-level map CRUD over IndexedDB
+  useCrossTab.ts        BroadcastChannel cross-tab commit relay
+  syncTypes.ts          SyncAdapter interface, error classification, result types
+  idbConnection.ts      Singleton IndexedDB connection (owns the upgrade callback)
+  idbSchema.ts          Typed DB schema (11 stores, 3 layer-owned + 8 legacy)
+  idbHelpers.ts         Commit/checkpoint/branch-head CRUD, sync cursor persistence
+index.ts                Barrel: re-exports @businessmaps/metaontology + all composables
+nuxt.config.ts          Nuxt layer config (auto-imports composables)
+```
+
+---
+
+## Design decisions
+
+**Singleton per tab, not per component.** Composable state lives at module level. `useCommitLog()` returns the same object whether called from a store, a sync engine, or a UI component. Cross-tab isolation is a property of JavaScript module loading (each tab loads its own module instance), not of per-call factoring. This avoids the class of bugs where two consumers see different commit histories.
+
+**Layer owns the IDB connection.** IndexedDB allows one upgrade callback per database version. Splitting the upgrade between the metaontology layer and the app would create a coordination problem (who runs first on a fresh install? who creates the legacy stores?). The layer creates every store the database needs; app code accesses the same connection through a thin proxy.
+
+**Transport-agnostic sync.** The `SyncAdapter` interface is three methods: `push`, `pull`, `getRemoteHead`. Encryption, authentication, presigned URLs, compression - all internal to the adapter. The sync engine handles debouncing, retry, merge, and error classification without knowing how commits move.
+
+**Commit-sourced, not snapshot-sourced.** Loading a map means loading the latest checkpoint and replaying commits since. The commit log is the source of truth; the model is a derived projection. This makes undo (append the inverse), sync (exchange commits), branching (fork the log), and merge (three-way merge of replayed states) all compose from the same data structure.
+
+**Unload safety without Service Worker.** Three browser signals (`visibilitychange` hidden, `pagehide`, `beforeunload`) trigger a fire-and-forget IDB flush. The cap-triggered flush (25 pending commits) limits the worst-case data loss to 24 commits during a crash. Combined, these cover tab close, navigation, mobile backgrounding, and back/forward cache entry.
+
+---
+
+## License
+
+Apache License 2.0
+
+Copyright 2025 Business Maps