pi-weave 0.1.7 → 0.1.9

package/src/web/client/live.ts

@@ -0,0 +1,151 @@
+/**
+ * The SSE socket, wired to {@link ./live.model} (weave-workspace §6).
+ *
+ * Everything that decides anything lives in `live.model.ts`. This file owns
+ * exactly one thing the model cannot: a real `EventSource`, its three
+ * listeners, and the fact that it must be closed. Keeping that separation
+ * sharp is what lets the whole liveness layer be unit-tested with no DOM —
+ * §10's constraint, and the reason `.model.ts` files exist at all.
+ *
+ * ## The socket is injected
+ *
+ * {@link startLive} takes a factory rather than calling `new EventSource`.
+ * The DOM one is the default at the call site in the shell, and a test passes
+ * a fake with the same four members. This is the same port-shaped injection
+ * `api.ts` uses for `fetch` and for the same reason: without it, the only way
+ * to reach the reconnect path would be a browser.
+ *
+ * ## Why the connection state is written here and not in the model
+ *
+ * The model is pure and returns a next state; something has to publish it to
+ * the `connection` signal that the status bar reads. That publication is this
+ * file's other job, and it is one line — which is the correct amount of logic
+ * for a file with no test harness behind it.
+ */
+
+import type { ChangeScope } from "../shared/wire";
+import { CHANGE_EVENT_NAME } from "../shared/wire";
+import type { LiveEvent, LiveState, RefetchPlan } from "./live.model";
+import { EVENTS_PATH, initialLiveState, isNoop, parseFrame, reduceLive, withStamp } from "./live.model";
+import { connection } from "./state";
+
+/**
+ * The slice of `EventSource` this module uses.
+ *
+ * Structural, so the platform's satisfies it without a cast and a fake is an
+ * object literal. Two details are load-bearing:
+ *
+ * **`addEventListener` for all three events, not `onopen`/`onerror`.** The
+ * handler properties are the more obvious spelling and they do not typecheck:
+ * a property of function type is checked *contravariantly* under
+ * `strictFunctionTypes`, so a port declaring `onopen: ((e: unknown) => void)`
+ * rejects the platform's `(ev: Event) => any` — `unknown` is not assignable
+ * to `Event`. Method declarations are compared bivariantly, so the single
+ * `addEventListener` form accepts the real `EventSource` without a cast and
+ * without this module ever naming a DOM type.
+ *
+ * **`{data: string}` rather than `MessageEvent`.** This file is compiled by
+ * `tsconfig.web.json` for the bundle *and* pulled into the root project when
+ * a test imports it, and the root project has no `DOM` lib. The narrow shape
+ * is the only one both projects can resolve. `open` and `error` carry no
+ * payload this module reads, so they receive it and ignore it.
+ */
+export interface EventSourceLike {
+  /** `0` connecting, `1` open, `2` closed. See `live.model.ts`'s constants. */
+  readonly readyState: number;
+  addEventListener(type: string, listener: (event: { data: string }) => void): void;
+  close(): void;
+}
+
+/** Creates a stream for a URL. The DOM's `EventSource` constructor fits. */
+export type EventSourceFactory = (url: string) => EventSourceLike;
+
+/** What {@link startLive} needs from its host. */
+export interface LiveOptions {
+  /** Injected socket constructor. */
+  open: EventSourceFactory;
+  /**
+   * Run a refetch plan. Async and awaited nowhere — a fetch that outlives the
+   * socket is the caller's problem to make idempotent, and the shell's is.
+   */
+  refetch: (plan: RefetchPlan) => void;
+  /** Whether a note is open, read fresh per event. See `reduceLive`. */
+  hasSelection: () => boolean;
+  /** The stream URL. Defaults to {@link EVENTS_PATH}. */
+  path?: string;
+}
+
+/** A running stream. */
+export interface LiveHandle {
+  /** Close the socket and mark the connection offline. Idempotent. */
+  stop(): void;
+  /** Force a full refetch — the header's `⟳`. */
+  refresh(): void;
+  /** Record a stamp the client now holds, so the next frame can dedupe it. */
+  seen(stamp: string): void;
+  /** Current state. For tests and the status bar's tooltip. */
+  state(): LiveState;
+}
+
+/**
+ * Attach to the event stream.
+ *
+ * Note what this does *not* do: reconnect. `EventSource` reconnects natively
+ * with its own backoff, which is most of why §6 chose it over a WebSocket, so
+ * a retry loop here would be a second one racing the browser's.
+ */
+export function startLive(opts: LiveOptions): LiveHandle {
+  let state = initialLiveState();
+  let stopped = false;
+
+  const source = opts.open(opts.path ?? EVENTS_PATH);
+
+  /** The single path from a socket event to a state change and a refetch. */
+  const dispatch = (event: LiveEvent): void => {
+    const next = reduceLive(state, event, opts.hasSelection());
+    state = next.state;
+    connection.value = state.connection;
+    if (!isNoop(next.plan)) opts.refetch(next.plan);
+  };
+
+  source.addEventListener("open", () => dispatch({ type: "open" }));
+  source.addEventListener("error", () => dispatch({ type: "error", readyState: source.readyState }));
+  source.addEventListener(CHANGE_EVENT_NAME, (event) => {
+    const frame = parseFrame(event.data);
+    // A frame we cannot read is dropped rather than escalated: the next one
+    // carries the same "something moved" meaning, and the heartbeat proves
+    // the socket is still alive meanwhile.
+    if (frame !== null) dispatch({ type: "frame", event: frame });
+  });
+
+  return {
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      source.close();
+      dispatch({ type: "closed" });
+    },
+    refresh() {
+      dispatch({ type: "refresh" });
+    },
+    seen(stamp: string) {
+      state = withStamp(state, stamp);
+    },
+    state() {
+      return state;
+    },
+  };
+}
+
+/**
+ * `new EventSource(url)`, as an {@link EventSourceFactory}.
+ *
+ * The one place in the liveness layer that names a DOM global, isolated here
+ * so that everything else in it compiles and runs under Node.
+ */
+export function domEventSource(url: string): EventSourceLike {
+  return new EventSource(url);
+}
+
+/** Re-exported so the shell imports its liveness vocabulary from one module. */
+export type { ChangeScope, LiveState, RefetchPlan };

package/src/web/client/main.tsx

@@ -0,0 +1,27 @@
+/**
+ * Client entry point (weave-workspace §2, §9).
+ *
+ * Reads the bootstrap block the HTML shell embedded, then mounts
+ * {@link Shell}. Everything else — layout, liveness, fetching — is reached
+ * from there.
+ *
+ * The three DOM reads that cannot be injected any further up (`getElementById`,
+ * `innerWidth`, `navigator.platform`) happen here and are passed down as
+ * props, so `Shell` and everything below it takes its world as parameters.
+ */
+
+import { render } from "preact";
+import { BOOTSTRAP_ELEMENT_ID } from "../shared/wire";
+import { readBootstrap } from "./bootstrap";
+import { Shell } from "./shell/Shell";
+import { installTheme } from "./shell/theme";
+
+const host = document.getElementById("app");
+if (host !== null) {
+  // Before the first render: the sheet carries the grid and the palette, and
+  // installing it after would show one unstyled frame. It copies the
+  // per-response CSP nonce off the server's own `<style>` — see `theme.ts`.
+  installTheme(document);
+  const boot = readBootstrap(document.getElementById(BOOTSTRAP_ELEMENT_ID)?.textContent ?? null);
+  render(<Shell cwd={boot.cwd} initialWidth={window.innerWidth} platform={navigator.platform} />, host);
+}

package/src/web/client/note/Editor.tsx

@@ -0,0 +1,102 @@
+/**
+ * The `<textarea>` editor and its toolbar (weave-workspace §0 V10, §11 P5.4).
+ *
+ * Props in, JSX out. Dirty tracking, the save lifecycle, conflict resolution
+ * and every string are `editor.model.ts`; the requests are `editor.ts`. What
+ * is left here is three elements and three handlers.
+ *
+ * A `<textarea>`, not CodeMirror 6, and §0 V10 settles it with a number:
+ * CM6 is 118 KB gzip — more than the entire rest of the client — against a
+ * 150 KB budget already 62 % spent. The textarea is what proves the *save
+ * path* is correct, which is the part P5 is actually gated on. Syntax
+ * highlighting can arrive later against a round trip that is already known
+ * to be lossless; the reverse order would be building an editor over a bug.
+ */
+
+import type { EditorEvent, EditorPrompt, EditorToolbar } from "./editor.model";
+import { OPEN_HINT, OPEN_LABEL } from "./editor.model";
+
+export interface EditorProps {
+  toolbar: EditorToolbar;
+  /** The `<textarea>`'s content — `state.draft`. */
+  draft: string;
+  /** The one prompt to show, or `null`. Ordered by `editorPrompt`. */
+  prompt: EditorPrompt | null;
+  /** Dispatch into the controller. The only way anything here changes state. */
+  send: (event: EditorEvent) => void;
+}
+
+/** The conflict / discard / external-change prompt. */
+function Prompt({ prompt, send }: { prompt: EditorPrompt; send: (event: EditorEvent) => void }) {
+  return (
+    <div class={`weave-note-prompt weave-note-prompt-${prompt.kind}`} role="alert">
+      <p class="weave-note-prompt-text">{prompt.message}</p>
+      <p class="weave-note-prompt-actions">
+        {prompt.actions.map((action) => (
+          <button key={action.label} type="button" class="weave-note-action" onClick={() => send(action.event)}>
+            {action.label}
+          </button>
+        ))}
+      </p>
+    </div>
+  );
+}
+
+/** The toolbar: edit/done, save, open-in-$EDITOR, and the status word. */
+export function EditorBar(props: EditorProps) {
+  const { toolbar, send } = props;
+  return (
+    <div class="weave-note-bar">
+      <button
+        type="button"
+        class="weave-note-toggle"
+        aria-pressed={toolbar.editing}
+        onClick={() => send({ type: "toggle" })}
+      >
+        {toolbar.toggleLabel}
+      </button>
+      {toolbar.editing ? (
+        <button type="button" class="weave-note-save" disabled={!toolbar.canSave} onClick={() => send({ type: "save" })}>
+          {toolbar.saveLabel}
+        </button>
+      ) : null}
+      <button type="button" class="weave-note-open" title={OPEN_HINT} onClick={() => send({ type: "open" })}>
+        {OPEN_LABEL}
+      </button>
+      {toolbar.dirty ? (
+        <span class="weave-note-dirty" title="unsaved changes" aria-hidden="true">
+          •
+        </span>
+      ) : null}
+      {toolbar.message === null ? null : <span class={`weave-note-status weave-note-status-${toolbar.tone}`}>{toolbar.message}</span>}
+      {props.prompt === null ? null : <Prompt prompt={props.prompt} send={send} />}
+    </div>
+  );
+}
+
+/**
+ * The editing surface.
+ *
+ * `⌘S` is handled here as well as globally, and deliberately: the global
+ * `keydown` listener sees every keystroke in the workspace, so claiming a
+ * modifier combination there is a workspace-wide claim. Handling it on the
+ * textarea too means the save fires from the element that owns the text even
+ * if the global map is later narrowed — and `keys.model.ts` returns `null`
+ * for anything it does not claim, so the two never fight over one event.
+ */
+export function Editor(props: EditorProps) {
+  return (
+    <textarea
+      class="weave-note-editor"
+      aria-label="Note body"
+      spellcheck
+      value={props.draft}
+      onInput={(event) => props.send({ type: "draft", text: (event.target as HTMLTextAreaElement).value })}
+      onKeyDown={(event) => {
+        if (event.key.toLowerCase() !== "s" || !(event.metaKey || event.ctrlKey)) return;
+        event.preventDefault();
+        props.send({ type: "save" });
+      }}
+    />
+  );
+}

package/src/web/client/note/Note.tsx

@@ -0,0 +1,113 @@
+/**
+ * The note column (weave-workspace §1.2, P2.4, P5).
+ *
+ * Props in, JSX out. The markdown pipeline, the sanitiser config, the
+ * wikilink resolution and every string are `note.model.ts`; the editor's
+ * dirty tracking, save lifecycle and conflict resolution are
+ * `editor.model.ts`. This file wires a click handler, sets `innerHTML` with
+ * content that has already been through all three of that module's layers,
+ * and swaps the rendered body for a `<textarea>` when the editor is open.
+ *
+ * `dangerouslySetInnerHTML` is used deliberately and exactly once. The
+ * alternative is parsing marked's output into a Preact tree, which means a
+ * second HTML parser in the bundle and a second place for a sanitisation
+ * mistake to hide. One clearly-marked line whose input is
+ * `renderNote(DOMPurify, …)` is easier to audit than a hundred lines that
+ * avoid the word "dangerously".
+ *
+ * The read view is rendered from the **note**, not from the draft: what the
+ * `<textarea>` holds is unsaved and un-sanitised, and piping it through
+ * `renderNote` on every keystroke would be a live preview paid for with a
+ * markdown parse and a DOMPurify pass per character. §11 P5.4 mentions a live
+ * preview; the honest version of it is `⌘E`, which is instant and shows the
+ * text that actually exists.
+ */
+
+import DOMPurify from "dompurify";
+import type { GraphPayload, NotePayload } from "../../shared/wire";
+import type { EditorEvent, EditorPrompt, EditorToolbar } from "./editor.model";
+import { Editor, EditorBar } from "./Editor";
+import type { NoteHeaderView } from "./note.model";
+import { noteEmptyMessage, noteHeader, renderNote, tagLabel, wikiIndex, wikilinkTargetOf } from "./note.model";
+
+export interface NoteProps {
+  note: NotePayload | null;
+  graph: GraphPayload | null;
+  selectedId: string | null;
+  onSelect: (id: string) => void;
+  /** Epoch ms for relative times. Injected so the render is deterministic. */
+  now: number;
+  /** The editor's view model, or `null` when the shell wired no editor. */
+  toolbar: EditorToolbar | null;
+  prompt: EditorPrompt | null;
+  /** The `<textarea>`'s content. Rendered only while `toolbar.editing`. */
+  draft: string;
+  send: (event: EditorEvent) => void;
+}
+
+function Header({ view }: { view: NoteHeaderView }) {
+  return (
+    <header class="weave-note-head">
+      <h3 class="weave-note-title">{view.title}</h3>
+      <p class="weave-note-meta">
+        <span class={`weave-prov weave-prov-${view.provenance}`} title={view.provenanceTitle}>
+          {view.provenanceGlyph} {view.provenance}
+        </span>
+        <span class="weave-note-time" title={view.updatedIso}>
+          updated {view.updated}
+        </span>
+        <span class="weave-note-time" title={view.createdIso}>
+          created {view.created}
+        </span>
+      </p>
+      <p class="weave-note-tags">
+        {view.tags.map((tag) => (
+          <span key={tag} class="weave-tag">
+            {tagLabel(tag)}
+          </span>
+        ))}
+      </p>
+    </header>
+  );
+}
+
+export function Note(props: NoteProps) {
+  const note = props.note?.note ?? null;
+  const empty = noteEmptyMessage(props.selectedId, note);
+  if (note === null) return <p class="weave-note-empty">{empty}</p>;
+
+  const index = wikiIndex(props.graph, note.slug);
+  // Bound once so TypeScript narrows it for both uses below: `toolbar.editing`
+  // is what decides whether the textarea renders, and reading it twice off
+  // `props` would need a non-null assertion at the second read.
+  const toolbar = props.toolbar;
+  const shell = { draft: props.draft, prompt: props.prompt, send: props.send };
+  return (
+    <article class="weave-note">
+      <Header view={noteHeader(note, props.now)} />
+      {toolbar === null ? null : <EditorBar toolbar={toolbar} {...shell} />}
+      {toolbar !== null && toolbar.editing ? (
+        <Editor toolbar={toolbar} {...shell} />
+      ) : (
+        <div
+          class="weave-note-body"
+          onClick={(event) => {
+            // A wikilink carries no href, so nothing is navigating; this only
+            // has to route the click onto the §1.3 context bus.
+            const target = wikilinkTargetOf(event.target as unknown as Parameters<typeof wikilinkTargetOf>[0]);
+            if (target !== null) props.onSelect(target);
+          }}
+          onKeyDown={(event) => {
+            if (event.key !== "Enter" && event.key !== " ") return;
+            const target = wikilinkTargetOf(event.target as unknown as Parameters<typeof wikilinkTargetOf>[0]);
+            if (target === null) return;
+            event.preventDefault();
+            props.onSelect(target);
+          }}
+          // Sanitised by `renderNote`'s three layers — see note.model.ts.
+          dangerouslySetInnerHTML={{ __html: renderNote(DOMPurify, note.body, index) }}
+        />
+      )}
+    </article>
+  );
+}

package/src/web/client/note/editor.controller.ts

@@ -0,0 +1,151 @@
+/**
+ * The editor's effects: three requests and an unload listener
+ * (weave-workspace §10, §11 P5).
+ *
+ * `editor.model.ts` decides *whether* to save, *what* to send and *what a
+ * response means*; it cannot issue a request or subscribe to `beforeunload`
+ * without ceasing to be pure. This is the other half — a controller whose
+ * every capability is injected, in the shape `search.ts` established.
+ *
+ * ## Why `editor.controller.ts` and not `editor.ts`
+ *
+ * The pairing everywhere else in the client is `x.model.ts` + `x.ts`
+ * (`search.model.ts`/`search.ts`, `live.model.ts`/`live.ts`), and that is the
+ * name this file wanted. It cannot have it: the component beside it is
+ * `Editor.tsx`, and on a case-insensitive filesystem — which is the macOS
+ * default — `editor.ts` and `Editor.tsx` are the same path prefix. TypeScript
+ * says so directly (`TS1149: File name … differs from already included file
+ * name … only in casing`) and the build is a hard error rather than a
+ * warning. Renaming the *component* instead would break the `.tsx` = view
+ * convention the whole client is read by, so the controller takes the longer
+ * name. The capabilities it needs are:
+ *
+ *  - a **`FetchLike`**, the same port `api.ts` takes, so no DOM is involved;
+ *  - a **`select`**, so completing a parked navigation goes through §1.3's
+ *    context bus rather than this module knowing what a selection is.
+ *
+ * The result is that the editor's whole asynchronous behaviour — the save
+ * round trip, the `409`, the stale-response guard, the unload block — is
+ * covered by ordinary unit tests, and `Editor.tsx` is a `<textarea>` and
+ * three handlers.
+ *
+ * ## Why the controller owns the dispatch loop
+ *
+ * Every event goes through {@link EditorHandle.send}, which reduces,
+ * publishes, and then performs whichever effect the transition asked for.
+ * There is no other path that mutates state. That is what makes "a save
+ * cannot start while a conflict is unresolved" and "a stale response cannot
+ * overwrite the draft" enforceable: the checks live in the reducer, and every
+ * response arrives back through here.
+ */
+
+import type { FetchLike } from "../api";
+import { openNote, saveNote } from "../api";
+import type { EditorEffect, EditorEvent, EditorState } from "./editor.model";
+import { initialEditorState, reduceEditor, shouldBlockUnload } from "./editor.model";
+
+/**
+ * The slice of `beforeunload` this module touches.
+ *
+ * Structural, and `returnValue` is included because that is the only form
+ * every browser still honours: `preventDefault()` alone is the spec's answer
+ * and Chrome ignored it for years. Setting both is the portable spelling.
+ */
+export interface BeforeUnloadEventLike {
+  preventDefault(): void;
+  returnValue?: unknown;
+}
+
+/** The slice of `window` the unload guard subscribes to. */
+export interface UnloadHost {
+  addEventListener(type: "beforeunload", listener: (event: BeforeUnloadEventLike) => void): void;
+  removeEventListener(type: "beforeunload", listener: (event: BeforeUnloadEventLike) => void): void;
+}
+
+/** What {@link createEditor} needs. Every capability injected. */
+export interface EditorOptions {
+  fetch: FetchLike;
+  /** The §1.3 context bus. Called to complete a navigation the editor held. */
+  select: (id: string | null) => void;
+  /** Called after every state change, so the component can re-render. */
+  onChange: (state: EditorState) => void;
+}
+
+/** A running editor. */
+export interface EditorHandle {
+  /** Current state. Read at render. */
+  state(): EditorState;
+  /** Dispatch an event. The only way state moves. */
+  send(event: EditorEvent): void;
+}
+
+export function createEditor(opts: EditorOptions): EditorHandle {
+  let state = initialEditorState();
+
+  const send = (event: EditorEvent): void => {
+    const next = reduceEditor(state, event);
+    state = next.state;
+    opts.onChange(state);
+    if (next.effect !== null) perform(next.effect);
+  };
+
+  const perform = (effect: EditorEffect): void => {
+    if (effect.type === "select") {
+      opts.select(effect.id);
+      return;
+    }
+    // Fire and forget: `api.ts` returns failures as values, so there is
+    // nothing to reject and nothing to catch. `void` documents the floating
+    // promise rather than hiding it — the same shape `workspace.ts` and
+    // `search.ts` use.
+    if (effect.type === "open") {
+      void (async () => {
+        const result = await openNote(opts.fetch, effect.slug);
+        send({ type: "opened", ok: result.ok && result.data.opened });
+      })();
+      return;
+    }
+    void (async () => {
+      const result = await saveNote(opts.fetch, effect.slug, effect.input);
+      if (result.ok) {
+        send({ type: "saved", payload: result.data });
+        return;
+      }
+      // The `409` is not an error in the sense the other five kinds are —
+      // it is the server handing back the information the user needs in
+      // order to choose. `api.ts` gives it its own arm for exactly this
+      // branch.
+      send(result.kind === "conflict" ? { type: "conflicted", conflict: result.conflict } : { type: "failed", message: result.message });
+    })();
+  };
+
+  return { state: () => state, send };
+}
+
+/**
+ * Block `beforeunload` while the draft is dirty. Returns an unsubscribe.
+ *
+ * The predicate is a thunk, not a value: a listener registered at mount
+ * outlives every render, so a captured state would answer with the editor as
+ * it was when the tab opened — which is always clean, making the guard a
+ * no-op that looks installed.
+ *
+ * No custom message: every browser has ignored the string since 2017 and
+ * shows its own wording. Returning one would be writing code whose only
+ * effect is to suggest, to the next reader, that it does something.
+ */
+export function watchUnload(host: UnloadHost, dirty: () => boolean): () => void {
+  const listener = (event: BeforeUnloadEventLike): void => {
+    if (!dirty()) return;
+    event.preventDefault();
+    // The legacy half. Chrome required a truthy `returnValue` long after the
+    // spec settled on `preventDefault`, and setting both is the only
+    // spelling that works everywhere.
+    event.returnValue = "";
+  };
+  host.addEventListener("beforeunload", listener);
+  return () => host.removeEventListener("beforeunload", listener);
+}
+
+/** {@link shouldBlockUnload}, re-exported so the shell imports one module. */
+export { shouldBlockUnload };