@plannotator/ui 0.39.0 → 0.41.0

package/utils/graphviz.ts

@@ -0,0 +1,93 @@
+/**
+ * Graphviz runtime slot — the same shape as `./mermaid`, one per engine so
+ * a host fills either independently.
+ *
+ * ONE code path feeds the renderer slot (`./diagram-render`):
+ * `loadGraphvizRuntime()`. It resolves at once from a filled slot and
+ * otherwise imports the engine lazily: `@viz-js/viz` (about 1.2 MB of
+ * Emscripten JS with the wasm inlined) is fetched on the first dot fence, a
+ * failed import is dropped from the memo so the next call issues a fresh
+ * `import()`, and the block re-attempts once and offers Retry. In
+ * Plannotator's single-file builds the import is inlined and resolves from
+ * the bundle; a host that bundles by route fetches it on demand.
+ *
+ * This module has NO static import of `@viz-js/viz`; the only place the
+ * dependency is named at runtime is the default loader's `import()`.
+ */
+import type { Viz } from '@viz-js/viz';
+
+export type GraphvizRuntime = Viz;
+
+/** Who filled the slot. */
+export type GraphvizRuntimeSource = 'loader' | 'host';
+
+export type GraphvizRuntimeLoader = () => Promise<Viz>;
+
+/** Default lazy loader: import the engine and instantiate its wasm once. */
+const defaultGraphvizLoader: GraphvizRuntimeLoader = () => import('@viz-js/viz').then((m) => m.instance());
+
+let runtime: Viz | null = null;
+let runtimeSource: GraphvizRuntimeSource | null = null;
+let loader: GraphvizRuntimeLoader = defaultGraphvizLoader;
+let pending: Promise<Viz> | null = null;
+
+/** Delay before the one automatic re-attempt after a failed lazy import. */
+let retryDelayMs = 750;
+
+/** Current runtime, or `null` while the slot is empty. */
+export function getGraphvizRuntime(): Viz | null {
+  return runtime;
+}
+
+/** How the current runtime was registered, or `null` while the slot is empty. */
+export function getGraphvizRuntimeSource(): GraphvizRuntimeSource | null {
+  return runtimeSource;
+}
+
+/** Register an already-instantiated engine (a host with its own import). */
+export function setGraphvizRuntime(next: Viz, source: GraphvizRuntimeSource = 'host'): void {
+  runtime = next;
+  runtimeSource = source;
+  pending = null;
+}
+
+/** The renderer's retry delay for the lazy path. */
+export function getGraphvizRetryDelayMs(): number {
+  return retryDelayMs;
+}
+
+/**
+ * Resolve the engine: at once from a filled slot, otherwise through the
+ * loader. A rejected load is dropped from the memo so the next call (the
+ * automatic re-attempt, a later mount, or the Retry button) issues a fresh
+ * `import()` instead of replaying the cached rejection.
+ */
+export function loadGraphvizRuntime(): Promise<Viz> {
+  if (runtime) return Promise.resolve(runtime);
+  if (!pending) {
+    const attempt = loader().then(
+      (loaded) => {
+        setGraphvizRuntime(loaded, 'loader');
+        return loaded;
+      },
+      (err: unknown) => {
+        if (pending === attempt) pending = null;
+        throw err;
+      },
+    );
+    pending = attempt;
+  }
+  return pending;
+}
+
+/** Test hook: empty the slot, stand in for the lazy import, shorten the retry delay. */
+export function __setGraphvizRuntimeLoaderForTests(
+  next: GraphvizRuntimeLoader | undefined,
+  options?: { retryDelayMs?: number },
+): void {
+  runtime = null;
+  runtimeSource = null;
+  pending = null;
+  loader = next ?? defaultGraphvizLoader;
+  retryDelayMs = options?.retryDelayMs ?? 750;
+}

package/utils/htmlChrome.ts

@@ -16,9 +16,16 @@ import { isStalePreference } from './preferenceTtl';
  *
  * `toolsHidden` is the header "Hide tools" toggle: while true, ALL floating
  * chrome over the page (sidebar tongue tabs + the comment/attachments
- * cluster) is removed from the DOM. Restoring it hidden can never strand a
- * user: the header button that flips it back is part of the header, not the
- * hidden chrome.
+ * cluster) is removed from the DOM. It DEFAULTS to true — an HTML document is
+ * authored to fill the viewport, so a first-ever session shows the page and
+ * nothing else, and the header eye (plus Mod+Shift+X) is what reveals the
+ * tools. Defaulting hidden can never strand a user for the same reason
+ * restoring hidden can't: the control that flips it back lives in the header,
+ * never in the hidden chrome. A fresh persisted record still wins in both
+ * directions, so a user who showed the tools keeps them next session —
+ * including in a folder annotate session, which restores and records the
+ * `toolsHidden` half while leaving the sidebar/panel halves to sessions whose
+ * sidebar it actually owns (see {@link mergeHtmlChromeState}).
  */
 
 const STORAGE_KEY = 'plannotator-html-chrome';
@@ -32,11 +39,14 @@ export interface HtmlChromeState {
   toolsHidden: boolean;
 }
 
-/** Default: both side surfaces closed — the page gets the viewport. */
+/**
+ * Default: both side surfaces closed AND the floating tools hidden — the page
+ * gets the whole viewport until the user asks for the tools.
+ */
 export const DEFAULT_HTML_CHROME_STATE: HtmlChromeState = {
   sidebarOpen: false,
   panelOpen: false,
-  toolsHidden: false,
+  toolsHidden: true,
 };
 
 /** Pure resolution logic (exported for tests): raw cookie value → state. */
@@ -68,6 +78,61 @@ export function resolveHtmlChromeState(
   }
 }
 
+/** Inputs to the restore-on-entry decision (see {@link shouldRestoreHtmlChrome}). */
+export interface HtmlChromeRestoreConditions {
+  /** The surface being rendered now is raw HTML or a live app. */
+  isHtmlSurface: boolean;
+  /** The surface rendered on the previous pass was too. */
+  wasHtmlSurface: boolean;
+  /** This session takes no part in the persisted chrome at all (archive, goal
+   *  setup): nothing is restored and nothing is written. A folder annotate
+   *  session is NOT suppressed — see {@link mergeHtmlChromeState}. */
+  suppressed: boolean;
+}
+
+/**
+ * Whether to apply the persisted chrome state, i.e. whether this render is an
+ * ENTRY into an HTML surface.
+ *
+ * The `wasHtmlSurface` term is what keeps navigation between two HTML
+ * documents from re-running the restore: `toolsHidden` defaults to true and a
+ * link click deliberately leaves the sidebar alone, so a re-run mid-session
+ * would flip both back under the user. Leaving an HTML surface for a markdown
+ * one and returning IS an entry, and restores again on purpose — that is what
+ * stops the markdown surface's sidebar state from leaking into the HTML
+ * cookie.
+ */
+export function shouldRestoreHtmlChrome(conditions: HtmlChromeRestoreConditions): boolean {
+  if (!conditions.isHtmlSurface) return false;
+  if (conditions.wasHtmlSurface) return false;
+  return !conditions.suppressed;
+}
+
+/**
+ * The record to persist when the chrome changes on an HTML surface.
+ *
+ * `sideSurfacesOwned` marks a session where the left sidebar and the
+ * annotations drawer are not this surface's to remember — a folder annotate
+ * session, whose file browser owns the sidebar for the whole session. Those two
+ * halves then keep whatever the last ordinary HTML session left, while the
+ * `toolsHidden` half is recorded normally: it is a property of the HTML surface
+ * itself and means the same thing in every session.
+ */
+export function mergeHtmlChromeState(input: {
+  /** The record on disk right now. */
+  persisted: HtmlChromeState;
+  /** The chrome this session is in. */
+  live: HtmlChromeState;
+  sideSurfacesOwned: boolean;
+}): HtmlChromeState {
+  if (!input.sideSurfacesOwned) return input.live;
+  return {
+    sidebarOpen: input.persisted.sidebarOpen,
+    panelOpen: input.persisted.panelOpen,
+    toolsHidden: input.live.toolsHidden,
+  };
+}
+
 export function getHtmlChromeState(): HtmlChromeState {
   return resolveHtmlChromeState(storage.getItem(STORAGE_KEY));
 }

package/utils/htmlLinkNavigation.ts

@@ -0,0 +1,196 @@
+/**
+ * What a link click inside a raw-HTML annotate document means.
+ *
+ * A srcdoc document has no URL of its own: its base URL is the PARENT page's,
+ * so `<a href="02-detail.html">` resolves onto the Plannotator server and the
+ * catch-all answers with the app itself — the whole editor rendered inside the
+ * annotated frame. The bridge therefore never lets the frame navigate and
+ * hands the RAW href to the parent, which is the trust boundary; this module
+ * is the pure decision it makes.
+ *
+ * Deliberately pure (no DOM, no fetch, no `window`): the caller passes the
+ * server origin and the directories, so every branch is unit-testable.
+ */
+
+import { hasLinkedDocExtension } from "./markdownExtensions";
+
+/** Longest href the parent will look at. Matches the bridge's own cap. */
+export const MAX_HTML_LINK_HREF_LENGTH = 2048;
+
+export type HtmlLinkIntent =
+	/**
+	 * A local document to open in the linked-doc overlay. `path` is absolute.
+	 * `rendersHtml` is whether it will open as another raw-HTML surface rather
+	 * than as markdown, which is what decides whether the sidebar is revealed:
+	 * HTML surfaces keep it closed and carry their own Back control.
+	 */
+	| { kind: "document"; path: string; hash: string; rendersHtml: boolean }
+	/** Another origin. Opens in a new tab; the frame never navigates. */
+	| { kind: "external"; url: string }
+	/** A local file Plannotator cannot render as a document (`.pdf`, `.zip`, …). */
+	| { kind: "unsupported"; path: string; label: string }
+	/** Nothing to do: empty, fragment-only, or a scheme we do not follow. */
+	| { kind: "ignored"; reason: HtmlLinkIgnoreReason };
+
+export type HtmlLinkIgnoreReason =
+	| "empty"
+	| "too-long"
+	| "fragment"
+	| "scheme"
+	| "invalid"
+	| "no-base";
+
+export interface HtmlLinkContext {
+	/** Directory of the document the click happened in. */
+	baseDir?: string | null;
+	/**
+	 * Directory the session was opened from. Server-absolute paths
+	 * (`/01-entry-point.html`, and the same path spelled with the server's own
+	 * origin) resolve against this, because that is the site root the author
+	 * meant when they wrote a root-relative link.
+	 */
+	rootDir?: string | null;
+	/** The Plannotator server's own origin, e.g. `http://localhost:19601`. */
+	serverOrigin: string;
+	/** The session's `--markdown` preference: HTML is Turndowned by `/api/doc`,
+	 *  so an `.html` target renders as markdown rather than as an HTML surface. */
+	convertHtml?: boolean;
+}
+
+/** Control characters never appear in a real href; they are how structure gets smuggled. */
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+const HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+
+export function resolveHtmlLinkIntent(
+	href: string,
+	context: HtmlLinkContext,
+): HtmlLinkIntent {
+	if (typeof href !== "string") return { kind: "ignored", reason: "invalid" };
+	const raw = href.trim();
+	if (!raw) return { kind: "ignored", reason: "empty" };
+	if (raw.length > MAX_HTML_LINK_HREF_LENGTH) return { kind: "ignored", reason: "too-long" };
+	if (CONTROL_CHARS.test(raw)) return { kind: "ignored", reason: "invalid" };
+	// The bridge scrolls in-page fragments itself; one reaching here is a no-op.
+	if (raw.startsWith("#")) return { kind: "ignored", reason: "fragment" };
+
+	// Scheme-relative (`//host/x`) and absolute URLs both go through URL
+	// parsing, which is the only reliable way to compare origins.
+	if (raw.startsWith("//") || HAS_SCHEME.test(raw)) {
+		return resolveAbsolute(raw, context);
+	}
+
+	const rootRelative = raw.startsWith("/");
+	const base = rootRelative ? context.rootDir : context.baseDir;
+	return resolveRelative(raw, base, context);
+}
+
+function resolveAbsolute(raw: string, context: HtmlLinkContext): HtmlLinkIntent {
+	let url: URL;
+	try {
+		url = new URL(raw, context.serverOrigin);
+	} catch {
+		return { kind: "ignored", reason: "invalid" };
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") {
+		// javascript:, data:, mailto:, tel:, file:, blob: — none of them name a
+		// document this session can annotate, and none may navigate the frame.
+		return { kind: "ignored", reason: "scheme" };
+	}
+	if (url.origin !== context.serverOrigin) {
+		return { kind: "external", url: url.href };
+	}
+	// The server's own origin: the author wrote `http://localhost:<port>/x.html`
+	// meaning "the file x.html of this site", so treat it as root-relative.
+	// Left alone it would hit the catch-all and render the app in the frame.
+	return resolveRelative(`${url.pathname}${url.hash}`, context.rootDir, context);
+}
+
+function resolveRelative(
+	raw: string,
+	baseDir: string | null | undefined,
+	context: HtmlLinkContext,
+): HtmlLinkIntent {
+	const { path: pathPart, hash } = splitHash(stripQuery(raw));
+	if (!pathPart) return { kind: "ignored", reason: "fragment" };
+	const decoded = decodePath(pathPart);
+	if (decoded === null || CONTROL_CHARS.test(decoded)) {
+		return { kind: "ignored", reason: "invalid" };
+	}
+	if (!baseDir) return { kind: "ignored", reason: "no-base" };
+	const resolved = joinPath(baseDir, decoded);
+	if (!resolved) return { kind: "ignored", reason: "invalid" };
+	// Containment is the server's call (`/api/doc` answers 403 for an escaping
+	// path). The extension gate is ours: a `.pdf` would be a pointless fetch
+	// and a confusing server error, so it is reported as unsupported here.
+	if (!hasLinkedDocExtension(resolved)) {
+		return { kind: "unsupported", path: resolved, label: basename(resolved) };
+	}
+	return {
+		kind: "document",
+		path: resolved,
+		hash,
+		rendersHtml: documentRendersHtml(resolved, context.convertHtml),
+	};
+}
+
+/**
+ * Whether opening `path` lands on another raw-HTML surface rather than a
+ * markdown one. `--markdown` sessions convert HTML on the way in, so nothing
+ * renders as HTML there. This is the one rule behind `rendersHtml`, and the
+ * same question the annotations panel's cross-file jump asks before deciding
+ * whether to reveal the sidebar — so it lives here rather than being spelled
+ * twice.
+ */
+export function documentRendersHtml(path: string, convertHtml?: boolean): boolean {
+	return /\.html?$/i.test(path) && !convertHtml;
+}
+
+function stripQuery(value: string): string {
+	const q = value.indexOf("?");
+	if (q < 0) return value;
+	const h = value.indexOf("#");
+	// `a.html?x=1#frag` — drop the query, keep the fragment.
+	return h > q ? value.slice(0, q) + value.slice(h) : value.slice(0, q);
+}
+
+function splitHash(value: string): { path: string; hash: string } {
+	const h = value.indexOf("#");
+	if (h < 0) return { path: value, hash: "" };
+	return { path: value.slice(0, h), hash: value.slice(h + 1) };
+}
+
+function decodePath(value: string): string | null {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return null;
+	}
+}
+
+function basename(path: string): string {
+	const parts = path.split("/");
+	return parts[parts.length - 1] || path;
+}
+
+/**
+ * Join a relative path onto a directory, resolving `.` and `..` lexically.
+ * A root-relative input (`/x.html`) is taken as relative to `baseDir` too —
+ * the caller has already chosen which directory plays the role of root.
+ */
+function joinPath(baseDir: string, relative: string): string | null {
+	const base = baseDir.replace(/\\/g, "/").replace(/\/+$/, "");
+	const rel = relative.replace(/\\/g, "/").replace(/^\/+/, "");
+	if (!rel) return null;
+	const segments = base.split("/");
+	for (const segment of rel.split("/")) {
+		if (!segment || segment === ".") continue;
+		if (segment === "..") {
+			// Never pop past the root marker (the leading "" of an absolute base).
+			if (segments.length > 1) segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+	const joined = segments.join("/");
+	return joined || null;
+}

package/utils/mermaid-eager.ts

@@ -3,23 +3,25 @@
  * at module evaluation (exactly where the old module-scope
  * `mermaid.initialize` ran) and fills the slot in `./mermaid`.
  *
- * `packages/editor/App.tsx` imports this module for its side effect, by
- * policy: Plannotator's own surfaces keep Mermaid in their entry chunk so it
- * can never fail separately from the app (on the share portal this is what
- * keeps `mermaid.core` out of a lazy chunk). The review editor does not import
- * it because it never renders a Mermaid block; adding the runtime there would
- * grow that bundle. A host that wants the same import adds:
+ * Plannotator does NOT import this module any more. Through @plannotator/ui
+ * 0.39.0 `packages/editor/App.tsx` imported it by policy so Mermaid stayed in
+ * the plan editor's entry chunk; with Mermaid 12 (ELK layout by default) the
+ * runtime is about 1.8 MB larger and the plan editor loads it on the first
+ * diagram instead, through the lazy path in `./mermaid`. The module is kept
+ * for hosts that want the runtime registered and initialized before the
+ * first render (a host that gates first paint on it, or that would rather
+ * not have a separate chunk that can fail on its own):
  *
  *   import '@plannotator/ui/utils/mermaid-eager';
  *
  * A host that does not import it gets the lazy path in `./mermaid`.
  *
  * The source tag passed below doubles as a build marker: the literal only
- * reaches a bundle when this module is evaluated in it, so a dropped or
- * tree-shaken side-effect import is caught by the built-HTML check in
- * tests/entry-assets.test.ts (the runtime itself stays inlined in a
- * single-file build through the loader's import(), so a Mermaid diagram id
- * cannot prove registration).
+ * reaches a bundle when this module is evaluated in it, which is how
+ * tests/entry-assets.test.ts proves on the built HTML that neither of
+ * Plannotator's bundles registers the runtime eagerly (the runtime itself is
+ * still inlined in a single-file build through the loader's import(), so a
+ * Mermaid diagram id cannot prove or disprove registration).
  */
 import mermaid from 'mermaid';
 import { MERMAID_CONFIG, setMermaidRuntime } from './mermaid';

package/utils/mermaid.ts

@@ -2,14 +2,20 @@
  * Mermaid runtime slot.
  *
  * ONE code path feeds `MermaidBlock`: `loadMermaidRuntime()`. It resolves at
- * once from a filled slot and otherwise imports the runtime lazily. Plannotator
- * fills the slot at module evaluation through `./mermaid-eager` (imported by
- * `packages/editor/App.tsx`), which keeps the runtime in its entry chunk on the
- * share portal exactly as it was with the static import, so it cannot fail
- * separately from the app. A host that does not import the eager entry gets
- * the lazy path: the runtime is fetched on the first diagram, a failed import
- * is dropped from the memo so the next call issues a fresh `import()`, and
- * the block re-attempts once and offers Retry.
+ * once from a filled slot and otherwise imports the runtime lazily: the
+ * runtime is fetched on the first diagram, a failed import is dropped from
+ * the memo so the next call issues a fresh `import()`, and the block
+ * re-attempts once and offers Retry.
+ *
+ * Since Mermaid 12 (ELK layout by default, about 1.8 MB more runtime than 11)
+ * the lazy path IS Plannotator's own path: `packages/editor/App.tsx` no longer
+ * imports `./mermaid-eager`, so a plan with no diagram never downloads the
+ * runtime in a chunked build (the share portal, any host that bundles by
+ * route). The single-file builds inline the `import('mermaid')` target through
+ * `inlineDynamicImports`, so there the lazy import resolves from the bundle
+ * itself and nothing is fetched. A host that wants the runtime registered at
+ * startup imports `./mermaid-eager`, which fills the slot at module
+ * evaluation; the slot then short-circuits this loader.
  *
  * This module has NO static import of `mermaid`; the only place the
  * dependency is named at runtime is the default loader's `import('mermaid')`.
@@ -49,7 +55,8 @@ export const MERMAID_CONFIG: MermaidConfig = {
 /**
  * Who filled the slot. The eager value doubles as a build marker: the literal
  * only reaches a bundle when `./mermaid-eager` is evaluated in it, which is
- * what `tests/entry-assets.test.ts` asserts on the built HTML.
+ * how `tests/entry-assets.test.ts` proves on the built HTML that Plannotator's
+ * own bundles do NOT register the runtime eagerly.
  */
 export type MermaidRuntimeSource = 'plannotator-mermaid-eager' | 'loader' | 'host';
 
@@ -69,7 +76,9 @@ let pending: Promise<Mermaid> | null = null;
 
 /**
  * Delay before the block's one automatic re-attempt after a failed lazy
- * import. Only chunking hosts can fail here; a filled slot never loads.
+ * import. Only chunked builds can fail here (the share portal, a host that
+ * bundles by route); a single-file build resolves the import from itself and
+ * a filled slot never loads.
  */
 let retryDelayMs = 750;