@shivaedev/work-board 0.6.1 → 0.7.1

package/src/page/startTemplates.ts

@@ -0,0 +1,103 @@
+export const startTemplates = [
+	{
+		file: "project.md",
+		label: "Project",
+		source: `---
+id: example.project
+kind: project
+criteria:
+  - id: readable-result
+    text: A reviewer can trace the result to its reasoning and recorded evidence.
+---
+# Project
+
+## Goal
+Describe the outcome and who needs it.
+
+## Scope and constraints
+Name what belongs here and what must remain outside this work.
+
+## Reading path
+- [Investigation](investigation.md)
+- [Agent result](result.md)
+
+## Acceptance
+The criterion above is a target, not a recorded pass.
+Record what was checked, the source revision, and remaining limitations.
+`,
+	},
+	{
+		file: "investigation.md",
+		label: "Investigation",
+		source: `---
+id: example.investigation
+kind: investigation
+relationships:
+  - kind: informs
+    target: example.project
+criteria:
+  - id: explained-choice
+    text: Options, evidence, tradeoffs and the recommendation are explicit.
+---
+# Investigation
+
+## Question and background
+Explain the decision in context; do not require the reader to reconstruct it.
+
+## Options and tradeoffs
+| Option | Benefit | Cost | Evidence |
+| --- | --- | --- | --- |
+| First option | Not recorded | Not recorded | Not recorded |
+| Second option | Not recorded | Not recorded | Not recorded |
+
+## Recommendation
+State your take and what remains uncertain.
+
+## Response needed
+Name the exact question and the choices. Do not imply that a response was recorded.
+
+[Project and acceptance target](project.md)
+`,
+	},
+	{
+		file: "result.md",
+		label: "Agent result",
+		source: `---
+id: example.result
+kind: result
+relationships:
+  - kind: implements
+    target: example.investigation
+  - kind: relates_to
+    target: example.project
+# Add evidence only after a real observation; replace every placeholder:
+# evidence:
+#   - criterion: example.project#readable-result
+#     source: ./evidence/reading-check.md
+#     method: Describe the actual check.
+#     outcome: Describe the observed result and its limits.
+#     observed_at: Use the actual ISO timestamp with timezone.
+#     checked_revision: Use the actual full source commit SHA.
+---
+# Agent result
+
+## Outcome and changes
+Explain what changed and why. Link the relevant source files or patch.
+
+## Reasoning
+[Investigation and alternatives](investigation.md)
+
+## Checks and evidence
+Not recorded. Replace this with actual commands, observations and local evidence links.
+Recorded evidence does not by itself establish verified acceptance.
+
+## Limits and unresolved questions
+Name failures, skipped checks, uncertainty and any response needed.
+
+## Next action
+State the next action and who needs to respond, if known.
+
+[Project and acceptance target](project.md)
+`,
+	},
+] as const;

package/src/page/style.ts

@@ -58,5 +58,42 @@ figure.diagram[data-state="failed"] .diagram-source { display: block; }
 @media (prefers-reduced-motion: reduce) { * { transition: none !important; animation: none !important; } }
 `;
 
+const documents = `
+.start-open { display: block; padding: 0 12px 18px; color: var(--sidebar-text); }
+.onboarding { max-width: 76ch; }
+.start-template textarea { display: block; box-sizing: border-box; width: 100%; margin: 12px 0; padding: 12px; font-family: var(--mono); font-size: 13px; color: var(--text); background: var(--surface); border: 1px solid var(--border); border-radius: 6px; }
+@media print {
+  .sidebar, .bar, .preferences, .reading-tools, .visual-tools { display: none !important; }
+  .workspace { display: block !important; }
+  .page { width: 100%; }
+  #doc { padding: 0; }
+  .doc pre, .doc table { white-space: pre-wrap; overflow: visible; }
+  figure.diagram[data-state="pending"] .diagram-source, figure.diagram[data-state="failed"] .diagram-source { display: block; }
+}
+
+.visual-document, .visual-callout { border: 1px solid var(--border); border-radius: 12px; padding: 1em 1.2em; margin: 1.2em 0; overflow-wrap: anywhere; }
+.visual-document > :last-child, .visual-callout > :last-child { margin-bottom: 0; }
+.visual-label { font-weight: 650; margin-top: 0; }
+.visual-value { font-size: 1.35em; font-variant-numeric: tabular-nums; }
+.visual-document progress { display: block; width: 100%; height: 1em; accent-color: var(--link); }
+.visual-timeline-entries { border-left: 2px solid var(--border); padding-left: 1.6em; }
+.visual-timeline-entries > li { padding: .3em 0 .7em .2em; }
+.visual-callout { border-left: 4px solid var(--link); background: var(--surface); }
+.visual-warning, .visual-caution { border-left-color: #b97720; }
+.visual-diagnostic { font-weight: 600; color: var(--muted); }
+@media print { .visual-document, .visual-callout { break-inside: avoid; } }
+`;
+
 export const style =
-	theme + layout + prose + board + diagrams + readingStyles() + searchStyles + metadataStyles + workStyle() + attentionStyle() + visualStyles;
+	theme
+	+ layout
+	+ prose
+	+ board
+	+ diagrams
+	+ readingStyles()
+	+ searchStyles
+	+ metadataStyles
+	+ workStyle()
+	+ attentionStyle()
+	+ visualStyles
+	+ documents;

package/src/render/board.ts

@@ -1,5 +1,8 @@
 import type { RootContent } from "mdast";
-import { markdownToMdast } from "satteri";
+import remarkDirective from "remark-directive";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
 
 export interface Section {
 	readonly heading: string;
@@ -58,7 +61,7 @@ const joined = (blocks: readonly string[]): string => blocks.join("\n\n");
 
 export const boardOf = (source: string): Board => {
 	const draft: Draft = { definitions: [], footer: undefined, intro: [], sections: [], title: "" };
-	const root = markdownToMdast(source);
+	const root = unified().use(remarkParse).use(remarkGfm).use(remarkDirective).parse(source);
 	const nodes = root.type === "root" ? root.children : [];
 	const lastHeading = nodes.findLastIndex((node) => node.type === "heading");
 	nodes.forEach((node, index) => {

package/src/render/callouts.ts

@@ -0,0 +1,29 @@
+import type { Root } from "mdast";
+import { visit as visitNodes } from "unist-util-visit";
+
+const alerts = new Set(["NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION"]);
+
+export function callouts() {
+	return function transform(tree: Root) {
+		visitNodes(tree, "blockquote", (node) => {
+			const [first] = node.children;
+			const text = first?.type === "paragraph" ? first.children.at(0) : undefined;
+			if (text?.type !== "text") {
+				return;
+			}
+			const match = /^\[!(?<kind>[A-Z]+)\](?:\n|$)/u.exec(text.value);
+			const named = match?.groups?.kind;
+			if (!(named && alerts.has(named))) {
+				return;
+			}
+			const kind = named.toLowerCase();
+			text.value = text.value.slice(match?.[0].length ?? 0);
+			node.children.unshift({
+				children: [{ type: "text", value: named[0] + kind.slice(1) }],
+				data: { hProperties: { className: ["visual-label"] } },
+				type: "paragraph",
+			});
+			node.data = { ...node.data, hName: "aside", hProperties: { className: ["visual-callout", `visual-${kind}`], role: "note" } };
+		});
+	};
+}

package/src/render/markdown.ts

@@ -3,8 +3,11 @@ import { createElement } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { MarkdownAsync } from "react-markdown";
 import rehypeRaw from "rehype-raw";
+import remarkDirective from "remark-directive";
 import remarkGfm from "remark-gfm";
 import type { PluggableList } from "unified";
+import { callouts } from "#render/callouts.ts";
+import { visualDocuments } from "#render/visualDocuments.ts";
 import { codeBlocks } from "./code.ts";
 import type { documentHeadings } from "./documentHeadings.ts";
 import { documentLinks } from "./documentLinks.ts";
@@ -38,7 +41,7 @@ export const renderMarkdown = Effect.fn("WorkBoard.renderMarkdown")(function* (s
 					children: source,
 					components: { img: ({ node: _node, ...props }) => createElement("img", { ...props, loading: "lazy" }) },
 					rehypePlugins: plugins,
-					remarkPlugins: [remarkGfm],
+					remarkPlugins: [remarkGfm, remarkDirective, visualDocuments, callouts],
 				}),
 			),
 	});

package/src/render/visual.ts

@@ -0,0 +1,100 @@
+import { Option, Schema } from "effect";
+import type { Paragraph, RootContent } from "mdast";
+import type { ContainerDirective } from "mdast-util-directive";
+import { MetricFields, ProgressFields } from "./visualFields.ts";
+
+function textOf(node: RootContent): string {
+	if ("value" in node) {
+		return node.value;
+	}
+	return "children" in node ? node.children.map((child) => textOf(child)).join("") : "";
+}
+
+function paragraph(value: string, className?: string): Paragraph {
+	return { children: [{ type: "text", value }], data: { hProperties: { className: className ? [className] : [] } }, type: "paragraph" };
+}
+
+function hasLink(node: RootContent): boolean {
+	if (node.type === "link") {
+		return node.url.trim().length > 0;
+	}
+	if (node.type === "linkReference") {
+		return node.identifier.trim().length > 0;
+	}
+	return "children" in node && node.children.some((child) => hasLink(child));
+}
+
+function provenance(node: ContainerDirective): boolean {
+	return node.children.some((child) => child.type === "paragraph" && textOf(child).toLowerCase().startsWith("source:") && hasLink(child));
+}
+
+function fields<A>(schema: Schema.ConstraintDecoder<A, never>, node: ContainerDirective): A {
+	const parsed = Schema.decodeUnknownOption(schema, { onExcessProperty: "error" })(node.attributes ?? {});
+	if (Option.isNone(parsed)) {
+		throw new Error("Invalid or unknown attributes.");
+	}
+	return parsed.value;
+}
+
+function metric(node: ContainerDirective) {
+	const { unit, value } = fields(MetricFields, node);
+	if (!provenance(node)) {
+		throw new Error("Name a source with a Source: Markdown link.");
+	}
+	node.children.splice(1, 0, paragraph(value === undefined || value === "unknown" ? "Not recorded" : `${value} ${unit}`, "visual-value"));
+}
+
+function progress(node: ContainerDirective, label: string) {
+	const { completed, total } = fields(ProgressFields, node);
+	if (!provenance(node)) {
+		throw new Error("Name a source with a Source: Markdown link.");
+	}
+	const known = typeof completed === "number" && typeof total === "number";
+	if (known && completed > total) {
+		throw new Error("Completed count exceeds total.");
+	}
+	function display(value: number | "unknown" | undefined) {
+		return typeof value === "number" ? String(value) : "Not recorded";
+	}
+	const tally = `Recorded tally: ${display(completed)} of ${display(total)}`;
+	node.children.splice(1, 0, paragraph(tally + (known && total > 0 ? "" : ". Percentage unavailable."), "visual-value"));
+	if (known && total > 0) {
+		node.children.splice(2, 0, {
+			children: [{ type: "text", value: tally }],
+			data: { hName: "progress", hProperties: { ariaLabel: `${label}: ${tally}`, max: String(total), value: String(completed) } },
+			type: "paragraph",
+		});
+	}
+}
+
+function timeline(node: ContainerDirective) {
+	fields(Schema.Struct({}), node);
+	const lists = node.children.filter((child) => child.type === "list");
+	const [list] = lists;
+	if (lists.length !== 1 || !list?.ordered || list.children.length === 0 || list.children.length > 100) {
+		throw new Error("Use one ordered list with 1–100 entries.");
+	}
+	if (list.children.some((item) => !hasLink(item) || textOf(item).trim().length === 0)) {
+		throw new Error("Each timeline entry needs text and a source link.");
+	}
+	list.data = { ...list.data, hProperties: { className: ["visual-timeline-entries"] } };
+}
+
+export function renderVisual(node: ContainerDirective) {
+	const [first] = node.children;
+	if (first?.type !== "paragraph" || textOf(first).trim().length === 0 || textOf(first).toLowerCase().startsWith("source:")) {
+		throw new Error("Start with a Markdown label paragraph.");
+	}
+	const label = textOf(first).trim();
+	if (node.name === "metric") {
+		metric(node);
+	}
+	if (node.name === "progress") {
+		progress(node, label);
+	}
+	if (node.name === "timeline") {
+		timeline(node);
+	}
+	first.data = { ...first.data, hProperties: { className: ["visual-label"] } };
+	node.data = { ...node.data, hName: "section", hProperties: { ariaLabel: label, className: ["visual-document", `visual-${node.name}`] } };
+}

package/src/render/visualDocuments.ts

@@ -0,0 +1,68 @@
+import type { Root, RootContent } from "mdast";
+import type { ContainerDirective, LeafDirective, TextDirective } from "mdast-util-directive";
+import { SKIP, visit as visitNodes } from "unist-util-visit";
+import { renderVisual } from "./visual.ts";
+
+type Directive = ContainerDirective | LeafDirective | TextDirective;
+const names = new Set(["metric", "progress", "timeline"]);
+
+function isDirective(node: { readonly type: string }): node is Directive {
+	return node.type === "containerDirective" || node.type === "leafDirective" || node.type === "textDirective";
+}
+
+function nested(node: RootContent): boolean {
+	return isDirective(node) || ("children" in node && node.children.some((child) => nested(child)));
+}
+
+function failureOf(node: Directive, source: string): string | undefined {
+	try {
+		if (!names.has(node.name)) {
+			throw new Error(`Unknown visual directive ${node.name}.`);
+		}
+		if (node.type !== "containerDirective") {
+			throw new Error("Use a ::: container directive.");
+		}
+		const length = new TextEncoder().encode(source.slice(node.position?.start.offset, node.position?.end.offset)).byteLength;
+		if (length > 65_536) {
+			throw new Error("Visual directive exceeds 64 KiB.");
+		}
+		if (node.children.some((child) => nested(child))) {
+			throw new Error("Nested visual directives are not supported.");
+		}
+		renderVisual(node);
+		return undefined;
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+}
+
+export function visualDocuments() {
+	return function transform(tree: Root, file: { readonly value: unknown }) {
+		const source = String(file.value);
+		visitNodes(tree, ["containerDirective", "leafDirective", "textDirective"], (directive, index, parent) => {
+			if (!isDirective(directive) || index === undefined || parent === undefined) {
+				return;
+			}
+			const failure = failureOf(directive, source);
+			if (failure === undefined) {
+				return;
+			}
+			const original = source.slice(directive.position?.start.offset, directive.position?.end.offset);
+			if (directive.type === "textDirective") {
+				parent.children.splice(index, 1, { type: "text", value: original });
+				return [SKIP, index + 1] as const;
+			}
+			parent.children.splice(
+				index,
+				1,
+				{
+					children: [{ type: "text", value: `Visual component could not be rendered: ${failure}` }],
+					data: { hProperties: { className: ["visual-diagnostic"] } },
+					type: "paragraph",
+				},
+				{ type: "code", value: original },
+			);
+			return [SKIP, index + 2] as const;
+		});
+	};
+}

package/src/render/visualFields.ts

@@ -0,0 +1,17 @@
+import { Schema, SchemaTransformation } from "effect";
+
+const NumberValue = Schema.String.check(Schema.isPattern(/\S/u)).pipe(Schema.decodeTo(Schema.Finite, SchemaTransformation.numberFromString));
+const Count = NumberValue.check(Schema.makeFilter((value) => (Number.isSafeInteger(value) && value >= 0) || "Expected a nonnegative safe integer"));
+const UnknownValue = Schema.Literal("unknown");
+
+export const MetricFields = Schema.Struct({
+	unit: Schema.String.check(Schema.isPattern(/\S/u)),
+	value: Schema.optional(Schema.Union([NumberValue, UnknownValue])),
+});
+export const ProgressFields = Schema.Struct({
+	completed: Schema.optional(Schema.Union([Count, UnknownValue])),
+	total: Schema.optional(Schema.Union([Count, UnknownValue])),
+});
+
+export type MetricFields = typeof MetricFields.Type;
+export type ProgressFields = typeof ProgressFields.Type;

package/src/rpc/contract.ts

@@ -18,7 +18,7 @@ const PageUrl = Schema.String.check(
 			const path = new URL(value, "http://127.0.0.1").pathname;
 			return (
 				path === "/"
-				|| ["/_board/work", "/_board/overview", "/_board/changes"].includes(path)
+				|| ["/_board/work", "/_board/overview", "/_board/changes", "/_board/start"].includes(path)
 				|| /^\/_board\/item\/[^/]+\/$/u.exec(path) !== null
 				|| /\.md$/iu.exec(path) !== null
 				|| "Expected a local reading URL"

package/src/search/entries.ts

@@ -1,9 +1,12 @@
 import { MarkdownAsync } from "react-markdown";
 import rehypeRaw from "rehype-raw";
+import remarkDirective from "remark-directive";
 import remarkGfm from "remark-gfm";
 import { fileUrl } from "#files/url.ts";
 import { boardOf } from "#render/board.ts";
+import { callouts } from "#render/callouts.ts";
 import { documentHeadings } from "#render/documentHeadings.ts";
+import { visualDocuments } from "#render/visualDocuments.ts";
 import { searchCollector } from "./collector.ts";
 import { linkCollector } from "./linkCollector.ts";
 
@@ -46,7 +49,7 @@ export async function entriesOf(source: string, file: string, home: boolean, bod
 			await MarkdownAsync({
 				children: board?.definitions ? `${fragment}\n\n${board.definitions}` : fragment,
 				rehypePlugins: [rehypeRaw, headings.plugin, plugin, linkCollector(links)],
-				remarkPlugins: [remarkGfm],
+				remarkPlugins: [remarkGfm, remarkDirective, visualDocuments, callouts],
 			});
 		}
 	}