phormat 0.0.5

package/README.md

@@ -0,0 +1,102 @@
+# Phormat
+
+Source-canonical block Markdown editor for Svelte 5. Markdown source is the persisted representation; a typed block tree is the in-memory editing model.
+
+> **Monorepo note:** The npm package is `phormat`. This repository folder may still be named `md-editor`.
+
+## Install
+
+```bash
+npm install phormat
+```
+
+**Peer dependencies** (install in your app):
+
+- `svelte` ^5.0.0
+- `phoundry-ui` >=0.0.18
+- `@iconify/svelte` ^4.0.0 || ^5.0.0
+
+In a Phoundry monorepo, use a `file:` dependency (e.g. `"phormat": "file:../md-editor"`) and run `npm run prepack` in this repo after editing package source.
+
+## Publishing
+
+Maintainers: see [docs/publishing.md](docs/publishing.md). Quick path: `npm run release` after `npm login` and ensuring `phoundry-ui@>=0.0.18` is on npm.
+
+## Styles
+
+Import Phormat styles once in your app CSS (chains `phoundry-ui` theme and Tailwind `@source` for packaged components):
+
+```css
+@import 'phormat/styles';
+```
+
+## Overlay setup
+
+Phormat uses phoundry-ui context menus and inline formatting popovers. Call `setupOverlays()` once in your root layout and render the overlay hosts:
+
+```svelte
+<script>
+  import { ContextMenuOverlay, PopoverOverlay, setupOverlays } from 'phoundry-ui';
+
+  setupOverlays();
+</script>
+
+<ContextMenuOverlay />
+<PopoverOverlay>
+  <!-- Optional: mount your inline toolbar as PopoverOverlay default child -->
+</PopoverOverlay>
+```
+
+See the [demo layout](src/routes/+layout.svelte) in this repo for a working example.
+
+## Quick start
+
+```svelte
+<script>
+  import { PhormatEditor } from 'phormat';
+
+  let source = $state('# Hello\n\nEdit me.');
+</script>
+
+<PhormatEditor
+  value={source}
+  onchange={(next) => (source = next)}
+  showToolbar={true}
+/>
+```
+
+For file-backed apps, the parent owns load/save and passes `value` / `onchange`; call `markSaved()` on the internal state only if you use `MarkdownEditor` directly. With `PhormatEditor`, track dirty state against your own on-disk baseline (see [package usage](docs/package-usage.md)).
+
+## Package exports
+
+| Import | Purpose |
+|--------|---------|
+| `phormat` | `PhormatEditor`, `MarkdownEditor` state class, model types and helpers |
+| `phormat/styles` | CSS entry (theme + Tailwind scan) |
+| `phormat/demo` | Browser-only demo helpers (file load, localStorage drafts, download) — not for production file I/O |
+
+## Documentation
+
+- [Package usage](docs/package-usage.md) — embedder API, props, dirty baseline, demo vs production boundaries
+- [Architecture overview](docs/architecture-overview.md) — internal pipeline and extension points (contributors)
+- [Context glossary](docs/context/CONTEXT.md) — domain terms
+
+## Demo app
+
+```bash
+npm install
+npm run dev
+```
+
+The SvelteKit route at `src/routes/+page.svelte` is a reference implementation using `phormat/demo` for browser file upload, draft recovery, and export.
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Demo dev server |
+| `npm run check` | Typecheck |
+| `npm run test` | Unit tests |
+| `npm run prepack` | Build library (`dist/`) |
+| `npm run pack:local` | Build + create `.tgz` for inspection |
+| `npm run release` | Patch version, build, `npm publish` |

package/dist/assets/example-test.svelte

@@ -0,0 +1,228 @@
+
+<h1>Markdown specification examples</h1>
+<p>Exercises every construct described in <code>docs/md-spec.md</code>.</p>
+<h2>Paragraphs and line breaks</h2>
+<p>First paragraph with a soft break:<br>
+continues on the next line without a new block.</p>
+<p>Second paragraph after a blank line.</p>
+<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
+<hr>
+<h2>Headings</h2>
+<h1>Heading 1</h1>
+<h2>Heading 2</h2>
+<h3>Heading 3</h3>
+<h4>Heading 4</h4>
+<h5>Heading 5</h5>
+<h6>Heading 6</h6>
+<hr>
+<h2>Emphasis and strong emphasis</h2>
+<p><em>italic</em>
+<strong>bold</strong>
+<strong><em>bold italic</em></strong>
+<del>crossed out</del></p>
+<hr>
+<h2>Lists</h2>
+<p><strong>Unordered</strong> (<code>-</code>, <code>*</code>, <code>+</code>):</p>
+<ul>
+<li>Item one</li>
+<li>Item two
+<ul>
+<li>Nested item</li>
+</ul>
+</li>
+</ul>
+<ul>
+<li>Star marker item</li>
+</ul>
+<ul>
+<li>Plus marker item</li>
+</ul>
+<p><strong>Ordered:</strong></p>
+<ol>
+<li>First</li>
+<li>Second</li>
+<li>Nested ordered item</li>
+</ol>
+<hr>
+<h2>Links and images</h2>
+<p>Inline link: <a
+  href="https://example.com"
+  title="optional title"
+  rel="nofollow"
+>link text</a></p>
+<p>Reference-style link: <a
+  href="https://example.com"
+  title="optional title"
+  rel="nofollow"
+>link text</a></p>
+<p>Unresolved reference (expect parse warning): [missing link][nope]</p>
+<p>Image
+<img
+  src="https://picsum.photos/400/200"
+  alt="alt text"
+  title="optional title"
+></p>
+<p>Image 100px
+<img
+  src="https://picsum.photos/400/200"
+  alt="alt text|100"
+  title="optional title"
+></p>
+<p>Image 200px left-aligned
+<img
+  src="https://picsum.photos/400/200"
+  alt="alt text|200:"
+  title="optional title"
+></p>
+<p>Image 200px center-aligned
+<img
+  src="https://picsum.photos/400/200"
+  alt="alt text|:200:"
+  title="optional title"
+></p>
+<p>Image full width
+<img
+  src="https://picsum.photos/400/200"
+  alt="alt text|-1"
+  title="optional title"
+></p>
+<hr>
+<h2>Code</h2>
+<p>Inline code: use <code>code</code> in a sentence.</p>
+<p>Fenced code block:</p>
+<pre class="language-javascript">{@html `<code class="language-javascript"><span class="token keyword">const</span> x <span class="token operator">=</span> <span class="token number">1</span><span class="token punctuation">;</span></code>`}</pre>
+<p>Indented code block (four spaces — deferred in parser):</p>
+<p>    const y = 2;</p>
+<hr>
+<h2>Blockquotes</h2>
+<blockquote>
+<p>Quoted text
+More quoted text</p>
+</blockquote>
+<blockquote>
+<p>Outer quote</p>
+<blockquote>
+<p>Inner nested quote</p>
+</blockquote>
+</blockquote>
+<hr>
+<h2>Escaping</h2>
+<p>Literal characters: *asterisk*, # hash, backslash \</p>
+<hr>
+<h2>Tables</h2>
+<table>
+<thead>
+<tr>
+<th align="left">Work item</th>
+<th align="left">Owner</th>
+<th align="left">Status</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="left"><strong>Ship</strong> <code>EditableTable</code> — Tab/Enter cell navigation</td>
+<td align="left">@alice</td>
+<td align="left">==In review==</td>
+</tr>
+<tr>
+<td align="left"><em>Document</em> table editing in <a href="docs/context/editor/tables.md">tables.md</a></td>
+<td align="left">@bob</td>
+<td align="left"><strong>Done</strong></td>
+</tr>
+<tr>
+<td align="left">Run <code>npm run check</code> + Vitest table specs before merge</td>
+<td align="left">CI</td>
+<td align="left"><strong>Required</strong></td>
+</tr>
+<tr>
+<td align="left">Replace <del>plain-text</del> cells with inline AST on parse</td>
+<td align="left">@carol</td>
+<td align="left">Blocked</td>
+</tr>
+<tr>
+<td align="left">Smoke-test upload of <code>example-test.md</code> in the editor</td>
+<td align="left">QA</td>
+<td align="left">Pending</td>
+</tr>
+</tbody>
+</table>
+<p>Alignment:</p>
+<table>
+<thead>
+<tr>
+<th align="left">Left</th>
+<th align="center">Center</th>
+<th align="right">Right</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="left">L</td>
+<td align="center">C</td>
+<td align="right">R</td>
+</tr>
+</tbody>
+</table>
+<hr>
+<h2>Autolinks</h2>
+<h4>Angle-bracket link</h4>
+<p><a href="https://example.com" rel="nofollow">https://example.com</a></p>
+<h4>Angle-bracket email</h4>
+<p><a href="mailto:test@example.com">test@example.com</a></p>
+<h4>Bare URL (deferred)</h4>
+<p><a href="https://example.com/bare" rel="nofollow">https://example.com/bare</a></p>
+<hr>
+<h2>Callouts</h2>
+<blockquote>
+<p>[!note] Note title
+Callout body continues here.</p>
+</blockquote>
+<blockquote>
+<p>[!warning] Warning title
+Be careful with this.</p>
+</blockquote>
+<blockquote>
+<p>[!tip] Tip title
+Helpful hint.</p>
+</blockquote>
+<h2>Toggle</h2>
+<p>+++ Toggle title
+Hidden or collapsible body content.
++++</p>
+<h2>Columns</h2>
+<p>||| First column content
+||| Second column content
+|||</p>
+<h2>Highlight</h2>
+<p>Plain highlight: ==highlighted text==</p>
+<p>Colored highlight: ==yellow:colored highlight==</p>
+<h2>Wiki links</h2>
+<p>Page link
+[[Page Title]]</p>
+<p>Suppressed toc wiki link
+[[toc]]</p>
+<hr>
+<h2>Mentions</h2>
+<p>User mention
+@username</p>
+<p>Page mention
+@[Page Reference]</p>
+<hr>
+<h2>Synced block</h2>
+<p>Embedded block reference (deferred — expect parse warning): {{block:example-id}}</p>
+<hr>
+<h2>Table of contents</h2>
+<p>::toc</p>
+<hr>
+<h2>Extended task list markers</h2>
+<ul class="contains-task-list">
+<li class="task-list-item"><input type="checkbox" disabled> Todo</li>
+<li class="task-list-item"><input type="checkbox" checked disabled> Done</li>
+<li>[/] In progress</li>
+<li>[&gt;] Deferred</li>
+<li>[?] Other marker</li>
+</ul>
+<p>Ordered task item:</p>
+<ol class="contains-task-list">
+<li class="task-list-item"><input type="checkbox" disabled> Ordered todo</li>
+</ol>

package/dist/debug/JsonDebug.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import JsonDebugNode from './JsonDebugNode.svelte';
+	import { SvelteSet } from 'svelte/reactivity';
+
+	let { data }: { data: unknown } = $props();
+
+	let expanded = $state(new SvelteSet<string>(['$']));
+
+	function toggle(path: string) {
+		if (expanded.has(path)) expanded.delete(path);
+		else expanded.add(path);
+	}
+</script>
+
+<div
+	class="overflow-x-auto rounded-lg border border-border-muted bg-surface-sunken p-3 font-mono text-xs leading-relaxed text-txt-secondary"
+>
+	<JsonDebugNode value={data} path="$" {expanded} {toggle} ancestors={new SvelteSet()} />
+</div>

package/dist/debug/JsonDebug.svelte.d.ts

@@ -0,0 +1,6 @@
+type $$ComponentProps = {
+    data: unknown;
+};
+declare const JsonDebug: import("svelte").Component<$$ComponentProps, {}, "">;
+type JsonDebug = ReturnType<typeof JsonDebug>;
+export default JsonDebug;

package/dist/debug/JsonDebugNode.svelte

@@ -0,0 +1,138 @@
+<script lang="ts">
+	import JsonDebugNode from './JsonDebugNode.svelte';
+	import { SvelteSet } from 'svelte/reactivity';
+
+	type Props = {
+		value: unknown;
+		path: string;
+		expanded: Set<string>;
+		toggle: (path: string) => void;
+		ancestors: Set<object>;
+	};
+
+	let { value, path, expanded, toggle, ancestors }: Props = $props();
+
+	const isOpen = $derived(expanded.has(path));
+
+	function childPathSegment(key: string | number): string {
+		if (typeof key === 'number') return `[${key}]`;
+		return `[${JSON.stringify(key)}]`;
+	}
+
+	function formatLeaf(v: unknown): string {
+		if (v === null) return 'null';
+		if (v === undefined) return 'undefined';
+		if (typeof v === 'string') return JSON.stringify(v);
+		if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+		if (typeof v === 'bigint') return `${String(v)}n`;
+		if (v instanceof Date) return v.toISOString();
+		if (typeof v === 'function') return '[Function]';
+		if (typeof v === 'symbol') return String(v);
+		return String(v);
+	}
+
+	function isPlainObject(v: unknown): v is Record<string, unknown> {
+		return (
+			typeof v === 'object' &&
+			v !== null &&
+			!Array.isArray(v) &&
+			Object.getPrototypeOf(v) === Object.prototype
+		);
+	}
+
+	const nextAncestors = $derived.by(() => {
+		if (value !== null && typeof value === 'object') {
+			const next = new SvelteSet(ancestors);
+			next.add(value as object);
+			return next;
+		}
+		return ancestors;
+	});
+
+	const arraySummary = $derived(Array.isArray(value) ? `Array(${value.length})` : '');
+
+	const objectSummary = $derived.by(() => {
+		if (!isPlainObject(value)) return '';
+		const keys = Object.keys(value);
+		const label = keys.length === 1 ? 'key' : 'keys';
+		return `Object(${keys.length} ${label})`;
+	});
+</script>
+
+{#if value === undefined}
+	<span class="text-txt-tertiary">undefined</span>
+{:else if value === null}
+	<span class="text-txt-tertiary">null</span>
+{:else if typeof value !== 'object'}
+	{#if typeof value === 'string'}
+		<span class="text-semantic-success/90">{formatLeaf(value)}</span>
+	{:else if typeof value === 'number' || typeof value === 'bigint'}
+		<span class="text-semantic-warning/90">{formatLeaf(value)}</span>
+	{:else if typeof value === 'boolean'}
+		<span class="text-accent-primary/90">{formatLeaf(value)}</span>
+	{:else}
+		<span class="text-txt-secondary">{formatLeaf(value)}</span>
+	{/if}
+{:else if ancestors.has(value as object)}
+	<span class="text-semantic-warning">[Circular]</span>
+{:else if Array.isArray(value)}
+	<div class="min-w-0">
+		<button
+			type="button"
+			class="flex w-full min-w-0 items-start gap-1 rounded px-0.5 py-0.5 text-left text-txt-primary hover:bg-surface-raised/80"
+			onclick={() => toggle(path)}
+		>
+			<span class="w-4 shrink-0 text-txt-tertiary select-none">{isOpen ? '▾' : '▸'}</span>
+			<span class="text-txt-secondary">{arraySummary}</span>
+		</button>
+		{#if isOpen}
+			<ul class="ml-4 border-l border-border-muted pl-2">
+				{#each value as item, i (i)}
+					<li class="flex gap-2 py-0.5">
+						<span class="shrink-0 text-txt-tertiary">{i}:</span>
+						<div class="min-w-0 flex-1">
+							<JsonDebugNode
+								value={item}
+								path={`${path}${childPathSegment(i)}`}
+								{expanded}
+								{toggle}
+								ancestors={nextAncestors}
+							/>
+						</div>
+					</li>
+				{/each}
+			</ul>
+		{/if}
+	</div>
+{:else if isPlainObject(value)}
+	<div class="min-w-0">
+		<button
+			type="button"
+			class="flex w-full min-w-0 items-start gap-1 rounded px-0.5 py-0.5 text-left text-txt-primary hover:bg-surface-raised/80"
+			onclick={() => toggle(path)}
+		>
+			<span class="w-4 shrink-0 text-txt-tertiary select-none">{isOpen ? '▾' : '▸'}</span>
+			<span class="text-txt-secondary">{objectSummary}</span>
+		</button>
+		{#if isOpen}
+			<ul class="ml-4 border-l border-border-muted pl-2">
+				{#each Object.keys(value).sort() as key (key)}
+					<li class="flex gap-2 py-0.5">
+						<span class="shrink-0 text-txt-tertiary">{JSON.stringify(key)}:</span>
+						<div class="min-w-0 flex-1">
+							<JsonDebugNode
+								value={value[key]}
+								path={`${path}${childPathSegment(key)}`}
+								{expanded}
+								{toggle}
+								ancestors={nextAncestors}
+							/>
+						</div>
+					</li>
+				{/each}
+			</ul>
+		{/if}
+	</div>
+{:else}
+	<span class="text-option-purple/90">{formatLeaf(value)}</span>
+{/if}

package/dist/debug/JsonDebugNode.svelte.d.ts

@@ -0,0 +1,11 @@
+import JsonDebugNode from './JsonDebugNode.svelte';
+type Props = {
+    value: unknown;
+    path: string;
+    expanded: Set<string>;
+    toggle: (path: string) => void;
+    ancestors: Set<object>;
+};
+declare const JsonDebugNode: import("svelte").Component<Props, {}, "">;
+type JsonDebugNode = ReturnType<typeof JsonDebugNode>;
+export default JsonDebugNode;

package/dist/demo/documentLifecycle.d.ts

@@ -0,0 +1,57 @@
+import type { MarkdownEditor } from '../editor/MarkdownEditor.svelte.js';
+import { type StoredDraft } from '../editor/draftPersistence.js';
+export type DemoSessionOrigin = 'new' | 'loaded_from_file' | 'draft_restored';
+export type DemoPersistenceKind = 'none' | 'marked_saved' | 'exported';
+export type LoadMDFileInput = Event | HTMLInputElement | File | null | undefined;
+export type LoadMarkdownFileResult = {
+    ok: true;
+    source: string;
+    fileName: string;
+    fingerprint: string;
+    pendingDraft: StoredDraft | null;
+} | {
+    ok: false;
+    error: string;
+};
+/** Browser demo session metadata (draft keys, conflict banners, export badges). */
+export type DemoDocumentSession = {
+    fingerprint: string | null;
+    origin: DemoSessionOrigin;
+    persistenceKind: DemoPersistenceKind;
+    lastMarkedSavedAt: number | null;
+    lastExportedAt: number | null;
+    pendingFileDraft: StoredDraft | null;
+    fileConflictDismissed: boolean;
+    diskSourceAtConflictDecision: string | null;
+};
+export declare function createDemoDocumentSession(): DemoDocumentSession;
+export declare function demoDraftStorageKey(session: DemoDocumentSession): string;
+export declare function shouldDeferDraftAutosave(session: DemoDocumentSession, currentSource: string): boolean;
+export declare function fileFromInput(input: LoadMDFileInput): File | null;
+export declare function loadMarkdownFile(file: File): Promise<LoadMarkdownFileResult>;
+export declare function loadMarkdownFileFromInput(input: LoadMDFileInput): Promise<LoadMarkdownFileResult>;
+export declare function applyLoadedFileToEditor(editor: MarkdownEditor, result: Extract<LoadMarkdownFileResult, {
+    ok: true;
+}>, session: DemoDocumentSession): void;
+export declare function restoreLocalDraft(editor: MarkdownEditor, session: DemoDocumentSession, source: string): void;
+export declare function discardLocalDraftSnapshot(session: DemoDocumentSession): void;
+export declare function restorePendingFileDraft(editor: MarkdownEditor, session: DemoDocumentSession): void;
+export declare function discardPendingFileDraft(session: DemoDocumentSession): void;
+export declare function dismissPendingFileDraftConflict(editor: MarkdownEditor, session: DemoDocumentSession): void;
+export declare function downloadMarkdownFile(editor: MarkdownEditor, session: DemoDocumentSession, fileName?: string | null): void;
+export declare function markDocumentSaved(editor: MarkdownEditor, session: DemoDocumentSession): void;
+/** Controlled demo: mark session saved without a {@link MarkdownEditor} instance. */
+export declare function markDemoSessionSaved(session: DemoDocumentSession): void;
+/** Controlled demo: restore local draft — returns source to assign to `value`. */
+export declare function restoreLocalDraftControlled(session: DemoDocumentSession, source: string): string;
+/** Controlled demo: apply pending file draft — returns draft source or null. */
+export declare function restorePendingFileDraftControlled(session: DemoDocumentSession): string | null;
+export declare function dismissPendingFileDraftConflictControlled(session: DemoDocumentSession, currentSource: string): void;
+/** Controlled demo: download source string as .md file. */
+export declare function downloadMarkdownSource(source: string, session: DemoDocumentSession, fileName?: string | null): void;
+export declare function applyLoadedFileControlled(result: Extract<LoadMarkdownFileResult, {
+    ok: true;
+}>, session: DemoDocumentSession): {
+    source: string;
+    fileName: string;
+};