Where the editor opens and saves

The component owns no persistence (SPEC): it hands documents to a host. A store is the host's answer to "where do ensembles live". Give the editor one and its Ensemble panel gains Open (the store's documents), Save (back to the document it came from), Save as, and History when the store keeps versions. Without one, the editor keeps a local draft and offers a download, as before.

interface EnsembleStore {
  list(): Promise<Array<{ id: string; name?: string; updated?: string }>>;
  read(id: string): Promise<Ensemble>;
  write(id: string, ensemble: Ensemble): Promise<{ id: string; revision?: string } | void>;
  history?(id: string): Promise<Array<{ revision: string; at?: string; author?: string; message?: string }>>;
  readRevision?(id: string, revision: string): Promise<Ensemble>;
  idFor?(src: string): string | null;
}

idFor maps a page url to the store's id, so a document opened by <tosi-ensemble-editor src="…"> (or a nested ensemble opened with Open inside) saves back to its entry instead of needing Save as. The editor fires loaded ({ src, storeId }) when a load lands.

When something fails

Every store call the editor makes is reported, never swallowed: a failed Open, History read, revision or Save dispatches error on the editor with { error } (a failed src load adds { src }), and the method's promise rejects with the same error. A failed Save leaves a document the editor opened or saved dirty, because it is: editor.dirty is true until a write succeeds, and the Ensemble panel's title carries a • while it is. dirty compares with the last copy loaded, handed over or written, so a document the store has never seen (after New or Open file…, or a src the store cannot name) is clean until it is edited and dirty after, which is what a host guarding unload needs. An edit made while a Save is in flight is not marked saved: what is written is the document as it was when Save was pressed.

From script: openFromStore(id), saveToStore(id?) (no id: back to the document's own entry; an id: Save as) and openRevision(revision), each resolving once the editor shows the result.

An id is the store's own address: a path on a dev server, a document id in a service. Two backends were in view when this was designed (board #3363, from Manta): a dev server writing the project's files, versioned by git, and a service (service-compris) holding documents with role-gated writes. Both fit.

The dev server's data store

tosijs-ui's dev server can let a page save the project's data files (editableData in site.config.ts, tosijs-ui 1.16.25+), and its tosijs-ui/doc-system/data-client module talks to it. dataClientStore adapts that module; pass it in, so this package does not depend on tosijs-ui:

import * as dataClient from "tosijs-ui/doc-system/data-client";
import { dataClientStore } from "tosijs-3d-ensemble";

editor.store = dataClientStore(dataClient, { dir: "static/ensembles" });

Its idFor takes same-origin urls in that folder and nothing else (a document from another host is never saved over a local file). tosijs-ui's site serves static/ at the root, so static/ensembles is at /ensembles/; pass servedAt when your folder is served somewhere else:

dataClientStore(dataClient, { dir: "static/assemblies", servedAt: "/assemblies" });

Saving is gated as source editing is: this machine, an edit session over the tunnel, or a LAN you named. A static host answers the endpoint with a page, so list() rejects there and a host can leave the store off.