create-obsidian-arrow 0.1.0

package/template/scripts/install-skills.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Install the skills bundled in this repo (skills/*) into the developer's agent
+ * via the `skills` CLI (https://github.com/vercel-labs/skills). This repo acts
+ * as a local marketplace: `skills add .` discovers skills/<name>/SKILL.md and
+ * lets the user pick which to install through the interactive TUI.
+ *
+ * Wired as `postinstall`, so it runs after `pnpm install`. To keep that safe it
+ * only launches the interactive TUI when attached to a real terminal — in CI or
+ * any non-interactive context it prints a hint and exits 0 instead of hanging.
+ * Run it on demand with `pnpm skills:install` (which passes --force).
+ *
+ *   SKIP_SKILLS_INSTALL=1   opt out entirely
+ *   pnpm skills:install      force the interactive install
+ */
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+
+const forced = process.argv.includes("--force");
+const isCI = Boolean(process.env.CI);
+const interactive = Boolean(process.stdout.isTTY && process.stdin.isTTY);
+const optedOut = process.env.SKIP_SKILLS_INSTALL === "1";
+
+if (!forced && (isCI || optedOut || !interactive)) {
+	console.log(
+		"[skills] Skipping interactive skill install (non-interactive/CI/opt-out).\n         Run `pnpm skills:install` to install the bundled skills via the npx skills TUI."
+	);
+	process.exit(0);
+}
+
+console.log("[skills] Launching `npx skills add .` — pick the skills to install in the TUI…\n");
+
+// `--yes` only auto-confirms npx fetching the `skills` package; the skills CLI's
+// own selection TUI still shows (we deliberately do not pass skills' `-y`).
+const result = spawnSync("npx", ["--yes", "skills", "add", "."], {
+	stdio: "inherit",
+	shell: process.platform === "win32",
+});
+
+if (result.error) {
+	console.error(
+		`[skills] Could not run npx skills (${result.error.message}).\n         Install manually: npx skills add .`
+	);
+	process.exit(0); // never fail an install over an optional convenience step
+}
+
+process.exit(result.status ?? 0);

package/template/scripts/lib/extract-app-css.mjs

@@ -0,0 +1,60 @@
+/**
+ * Pure asar parsing for Obsidian's bundled app.css. No filesystem, no deps —
+ * takes a Buffer, returns the app.css string. Kept separate from the CLI so it
+ * can be unit-tested against a synthetic asar (CI has no Obsidian install).
+ *
+ * asar = Chromium Pickle header + concatenated data section:
+ *   [0,4)   UInt32LE = 4                  (outer pickle length prefix)
+ *   [4,8)   UInt32LE = headerPickleSize   (4-byte aligned — includes padding)
+ *   [8,12)  UInt32LE = json pickle payload size
+ *   [12,16) UInt32LE = json string length
+ *   [16, 16+jsonLen) = header JSON
+ *   data section starts at 8 + headerPickleSize  ← offset 4, NOT 8
+ *
+ * Using offset 8 (the inner payload size) instead of 4 yields a data start that
+ * is a few bytes short, bleeding bytes from the previous file into the slice —
+ * the alignment bug this module's test guards against.
+ */
+
+/** Read the header JSON + data-section start from an asar buffer. */
+export function readAsarHeader(buf) {
+	const jsonLen = buf.readUInt32LE(12);
+	const header = JSON.parse(buf.toString("utf8", 16, 16 + jsonLen));
+	const dataStart = 8 + buf.readUInt32LE(4);
+	return { header, dataStart };
+}
+
+/** Find a file entry by name anywhere in the asar header tree. */
+export function findEntry(header, fileName) {
+	let found = null;
+	(function walk(node) {
+		if (!node?.files) return;
+		for (const [name, child] of Object.entries(node.files)) {
+			if (name === fileName && child.offset != null) found = child;
+			if (child.files) walk(child);
+		}
+	})(header);
+	return found;
+}
+
+/** Extract `app.css` (or `fileName`) from an asar buffer as a string. */
+export function extractAppCss(buf, fileName = "app.css") {
+	const { header, dataStart } = readAsarHeader(buf);
+	const entry = findEntry(header, fileName);
+	if (!entry) throw new Error(`${fileName} not found inside the asar header`);
+	const start = dataStart + Number.parseInt(entry.offset, 10);
+	return buf.toString("utf8", start, start + entry.size);
+}
+
+/** Sanity-check that an extracted string is really Obsidian's app.css. */
+export function assertLooksLikeAppCss(css) {
+	const head = css.trimStart().slice(0, 64);
+	if (!head.startsWith("/*") && !head.startsWith(":root") && !head.startsWith("@")) {
+		throw new Error(
+			`Extracted CSS does not start as expected (got: ${JSON.stringify(head)}). The asar data offset may be misaligned.`
+		);
+	}
+	if (!css.includes("--text-accent") || !css.includes("body.theme-dark")) {
+		throw new Error("Extracted CSS is missing expected Obsidian theme variables.");
+	}
+}

package/template/scripts/pull-app-css.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Extract Obsidian's `app.css` from the local install and write it to
+ * `public/app.css`, so the sandbox renders against the *real* Obsidian default
+ * theme (every `var(--…)` token plus the semantic component rules like
+ * `.setting-item`, `.clickable-icon`, `.vertical-tab-nav-item`).
+ *
+ * On macOS `app.css` lives inside the asar archive
+ * `Obsidian.app/Contents/Resources/obsidian.asar`. The asar parsing lives in
+ * ./lib/extract-app-css.mjs (unit-tested separately).
+ *
+ * Usage:
+ *   node scripts/pull-app-css.mjs                # auto-locate per platform
+ *   node scripts/pull-app-css.mjs --path <asar>  # explicit asar/app.css path
+ *   OBSIDIAN_ASAR=<path> node scripts/pull-app-css.mjs
+ *
+ * Pure Node, no dependencies, no running Obsidian required.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertLooksLikeAppCss, extractAppCss } from "./lib/extract-app-css.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const outFile = path.resolve(__dirname, "..", "public", "app.css");
+
+function parseArgs(argv) {
+	const args = {};
+	for (let i = 0; i < argv.length; i++) {
+		if (argv[i] === "--path") args.path = argv[++i];
+	}
+	return args;
+}
+
+/** Candidate asar locations per platform, in priority order. */
+function candidateAsarPaths() {
+	const home = os.homedir();
+	switch (process.platform) {
+		case "darwin":
+			return [
+				"/Applications/Obsidian.app/Contents/Resources/obsidian.asar",
+				path.join(home, "Applications/Obsidian.app/Contents/Resources/obsidian.asar"),
+			];
+		case "win32":
+			return [path.join(home, "AppData/Local/Obsidian/resources/obsidian.asar")];
+		default:
+			return [
+				"/opt/Obsidian/resources/obsidian.asar",
+				"/usr/lib/obsidian/resources/obsidian.asar",
+				path.join(home, ".local/share/obsidian/resources/obsidian.asar"),
+			];
+	}
+}
+
+function locateSource(explicit) {
+	if (explicit) return explicit;
+	if (process.env.OBSIDIAN_ASAR) return process.env.OBSIDIAN_ASAR;
+	for (const p of candidateAsarPaths()) {
+		if (fs.existsSync(p)) return p;
+	}
+	return null;
+}
+
+function main() {
+	const { path: explicit } = parseArgs(process.argv.slice(2));
+	const source = locateSource(explicit);
+
+	if (!source) {
+		console.error(
+			`Could not locate Obsidian. Pass --path <obsidian.asar | app.css> or set OBSIDIAN_ASAR.\nLooked in:\n  ${candidateAsarPaths().join("\n  ")}`
+		);
+		process.exit(1);
+	}
+
+	const css = source.endsWith(".css")
+		? fs.readFileSync(source, "utf8")
+		: extractAppCss(fs.readFileSync(source));
+
+	assertLooksLikeAppCss(css);
+
+	fs.mkdirSync(path.dirname(outFile), { recursive: true });
+	fs.writeFileSync(outFile, css);
+	console.log(
+		`Wrote ${(css.length / 1024).toFixed(1)}KB to ${path.relative(process.cwd(), outFile)}\n` +
+			`  source: ${source}`
+	);
+}
+
+main();

package/template/skills/arrow-js-obsidian-patterns/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: arrow-js-obsidian-patterns
+description: Use when building reactive Obsidian plugin UI with @arrow-js/core beyond basic templates — icons (Obsidian uses Lucide; the data-icon sweep since setIcon can't run inside templates), CSS scoping/specificity against Obsidian's global rules, component mount/unmount lifecycle in an ItemView, and organizing shared reactive state. Complements arrow-js-obsidian-templates (syntax) with integration patterns.
+---
+
+# Arrow.js + Obsidian integration patterns
+
+How to build real components (not just template syntax) for an Obsidian plugin
+view with `@arrow-js/core`. Pairs with **arrow-js-obsidian-templates** (the
+template rules + footguns).
+
+## Mount / unmount lifecycle
+
+A view mounts a component imperatively, the same call the sandbox makes:
+
+```ts
+import { html } from "@arrow-js/core"
+// in ItemView.onOpen():
+this.contentEl.empty()
+html`${MyComponent()}`(this.contentEl)
+```
+
+- `html\`\`(container)` does **not** reliably return an unmount function — don't
+  gate cleanup on its return value. Always `container.empty()` before remounting.
+- Re-rendering on route/state change: clear the container, then mount fresh.
+  Reactive bindings (`${() => …}`) update in place — don't remount the whole tree
+  on every state change; let Arrow patch the slots that read changed state.
+
+## Shared reactive state
+
+One `reactive()` object is the single source of truth; components read it via
+getters so they stay in sync without prop-drilling.
+
+```ts
+import { reactive } from "@arrow-js/core"
+export const state = reactive({ model: "", streaming: false, items: [] })
+// pass getters into components: Toggle(() => state.streaming, () => { ... })
+```
+
+## Icons (Obsidian uses Lucide)
+
+`setIcon(el, name)` needs a real DOM element, so it **cannot** be called inside
+an Arrow template expression (the element doesn't exist yet). Two options:
+
+1. **In-plugin — the data-icon sweep.** Emit a placeholder, then sweep after
+   mount:
+
+   ```ts
+   html`<span class="svg-icon" data-icon="copy"></span>`
+   // after template(container) — scope the query to the container, not document:
+   for (const el of Array.from(container.querySelectorAll<HTMLElement>("[data-icon]"))) {
+     const name = el.getAttribute("data-icon")
+     if (name) setIcon(el, name)  // setIcon from "obsidian"
+   }
+   ```
+   For sections that open after mount (dropdowns/popovers), run the sweep in a
+   `nextTick(...)` after they render, scoped to that section's element.
+
+2. **In the sandbox (no `obsidian` module).** Use a Lucide import or inline SVG,
+   or plain text/emoji for chrome. The baseline uses text glyphs to stay
+   shim-free; add a Lucide-backed `setIcon` shim (aliased as `obsidian`) when you
+   port icon-using components in.
+
+## CSS scoping & specificity (the big one)
+
+Obsidian's `app.css` applies global rules like
+`button:not(.clickable-icon) { background: var(--interactive-normal) }` at
+specificity **(0,1,1)**. A plain `.my-btn` selector is **(0,1,0)** and loses
+regardless of cascade order.
+
+```css
+/* (0,1,0) — LOSES to Obsidian's global button rule */
+.my-action { background: var(--interactive-accent); }
+
+/* (0,2,1) — WINS, and can't leak */
+.my-panel button.my-action { background: var(--interactive-accent); }
+```
+
+Rules: prefer Obsidian's own classes (`.setting-item`, `.clickable-icon`,
+`.workspace-leaf`, `.vertical-tab-*`, `.modal`) and `var(--…)` tokens first; only
+add custom CSS where there's no Obsidian class; always scope custom rules under a
+container class + element type.
+
+## Common Obsidian layout classes
+
+- `.workspace-leaf` > `.workspace-leaf-content` — a view pane.
+- `.view-header` / `.view-content` — pane header + body.
+- `.setting-item` (+ `.setting-item-info` / `.setting-item-name` /
+  `.setting-item-description` / `.setting-item-control`) — settings rows.
+- `.checkbox-container` (+ `.is-enabled`) — toggle.
+- `.clickable-icon` — icon button (escapes the global button background rule).
+- `.vertical-tab-header` / `.vertical-tab-nav-item` (+ `.is-active`) — tab nav.
+- `.modal-container` > `.modal` — modal/popover.
+- `.mod-cta` — primary call-to-action button.

package/template/skills/arrow-js-obsidian-templates/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: arrow-js-obsidian-templates
+description: Use when writing @arrow-js/core (v1.0.6) html`` templates — the reactive-vs-static rule, full-value attribute binding (returning false removes the attribute), .property and @event binding, keyed lists, async component(fn, { fallback }) wrapped in boundary(), and the footguns: no literal HTML comments inside templates and no partial attribute values (both throw "Invalid HTML position" at render), plus @event handlers must type the param as Event not a narrowed subtype like MouseEvent (TS2345).
+---
+
+# Arrow.js Templates (v1.0.6)
+
+Rules for writing `html\`\`` templates that render correctly in the browser and
+inside an Obsidian plugin. Several of these are hard runtime errors, not style.
+
+## Reactive vs static — the core rule
+
+```ts
+import { html, reactive } from "@arrow-js/core"
+const data = reactive({ count: 0 })
+
+html`<span>${data.count}</span>`        // ❌ renders ONCE — never updates
+html`<span>${() => data.count}</span>`  // ✅ tracked — updates only this slot
+```
+
+`${value}` is read once at mount. `${() => value}` is tracked: Arrow records the
+reactive reads inside the function and re-runs **only that slot** when they
+change. Forgetting `() =>` is the #1 "why isn't it updating" bug.
+
+## Attributes
+
+An attribute expression must be the **entire** attribute value:
+
+```ts
+html`<div class="${() => (active() ? "tab is-active" : "tab")}">`  // ✅
+html`<div class="tab ${() => active() ? "is-active" : ""}">`        // ❌ THROWS
+```
+
+Partial values (`"static ${…}"`) are not registered as placeholders and throw
+`Invalid HTML position`. Build the full string in one expression.
+
+Returning `false` from an attribute expression **removes** the attribute (vs `""`
+which keeps it present-but-empty) — the clean way to toggle `disabled`/`hidden`:
+
+```ts
+html`<button disabled="${() => !canSubmit()}">Save</button>`
+```
+
+## Properties, events, lists
+
+```ts
+html`<input .value="${() => data.text}" />`                 // .prop = IDL property
+html`<button @click="${() => data.count++}">+</button>`     // @event
+html`${() => data.items.map((i) => html`<li>${i.text}</li>`.key(i.id))}`  // keyed list
+```
+
+Keyed lists preserve DOM across reorders; mutate item fields in place for
+fine-grained updates instead of replacing the whole array.
+
+## Async sections
+
+```ts
+import { boundary } from "@arrow-js/framework"
+const Card = component(
+  async () => { const d = await load(); return html`<div>${d.label}</div>` },
+  { fallback: html`<div>Loading…</div>` }   // shown while pending
+)
+html`${boundary(Card())}`
+```
+
+Works client-side with no SSR. `boundary()` only takes `{ idPrefix }`; the
+visible loading state comes from the async component's `fallback` option.
+
+## Event handler typing
+
+An `@event` handler must be assignable to `(e: Event) => void`. A handler typed
+with a narrowed subtype fails (parameter contravariance) — `tsc` reports
+`TS2345 … not assignable to 'ArrowExpression'`. Type the param `Event` and
+narrow inside; no-arg handlers are always fine.
+
+```ts
+// ❌ TS2345 — narrowed param
+html`<div @mousedown="${(e: MouseEvent) => resize(e)}">`
+// ✅ widen, narrow inside
+html`<div @mousedown="${(e: Event) => resize(e as MouseEvent)}">`
+```
+
+(document.addEventListener handlers are unaffected — they're DOM-lib typed.)
+
+## Hard footguns
+
+Render-time (pass `tsc`, fail only at render — always verify in a browser):
+
+1. **No literal HTML comments inside templates.** Arrow uses HTML comments as
+   expression-slot markers, so a literal `<!-- … -->` inflates the slot count and
+   throws `Invalid HTML position`. Use JS `//` comments outside the template.
+2. **No partial attribute values** — the expression must be the whole value
+   (see Attributes above), else `Invalid HTML position`.
+
+Type-time (caught by `tsc`):
+
+3. **No narrowed `Event` subtype in `@event` handlers** (see Event handler
+   typing above).
+
+CI guards all three: `test/template-footguns.test.mjs` scans for `<!--` and for
+inline handlers typed with a narrowed Event subtype; `tsc` covers the rest.

package/template/skills/obsidian-arrow-sandbox/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: obsidian-arrow-sandbox
+description: Use when prototyping or building Arrow.js UI for an Obsidian plugin in the obsidian-arrow-sandbox project — covers running the sandbox, pulling Obsidian's real app.css from the local install, the dev/verify workflow, CSS scoping, and porting a finished component into a plugin's ItemView with near-zero refactoring.
+---
+
+# Obsidian Arrow Sandbox
+
+A client-only Vite + TypeScript environment for building [Arrow.js](https://arrow-js.com/)
+UI that drops into an Obsidian plugin. Components render against Obsidian's real
+`app.css`, so what you see in the browser is what you get in a plugin view.
+
+## Mental model
+
+- **Client-only, no SSR.** Components use `@arrow-js/core` (`reactive`, `html`,
+  `component`, `watch`) plus `@arrow-js/framework` (`boundary` for async
+  sections), mounted via `template(container)` — the exact call an Obsidian
+  `ItemView.onOpen()` makes. Do **not** add `@arrow-js/ssr` or `@arrow-js/hydrate`;
+  an Obsidian plugin has no server and nothing to hydrate.
+- **Styling is Obsidian's, not yours.** `index.html` puts Obsidian body classes
+  (`theme-dark mod-macos …`) on `<body>` and loads the extracted `app.css`, which
+  defines every `var(--…)` token and semantic class (`.setting-item`,
+  `.clickable-icon`, `.vertical-tab-*`).
+
+## Run it
+
+```sh
+pnpm install
+pnpm pull-css     # extract Obsidian's app.css (macOS auto-detect)
+pnpm dev          # Vite + HMR; open the printed URL
+```
+
+`pnpm pull-css` reads `app.css` out of `obsidian.asar`. macOS is auto-detected;
+elsewhere pass `--path <obsidian.asar|app.css>` or set `OBSIDIAN_ASAR=<path>`.
+`public/app.css` is **git-ignored** (Obsidian's proprietary CSS — not
+redistributed), so run `pnpm pull-css` once before `pnpm dev`.
+
+## Build a component
+
+Add `src/components/MyThing.ts` exporting an Arrow `component()`, then mount it
+from `src/main.ts`. Use Obsidian classes + `var(--…)` tokens first; add custom
+CSS only when there's no Obsidian class, and scope it under a container class +
+element type (e.g. `.oas-frame button.oas-x`) so it beats Obsidian's global
+`button:not(.clickable-icon)` rule. Sandbox-only chrome lives in
+`src/sandbox/sandbox.css`.
+
+For the template-writing rules and Arrow's hard footguns, use the companion
+skill **arrow-js-obsidian-templates**.
+
+## Verify before claiming done
+
+```sh
+pnpm typecheck && pnpm test && pnpm lint   # or: pnpm check
+```
+
+Then open the `pnpm dev` URL and confirm the console is clean and the component
+looks like a real Obsidian pane. Arrow's footguns only surface at render, so
+typecheck passing is **not** proof a component works.
+
+## Port into the plugin
+
+Copy the component file into the plugin's view directory and mount it from
+`ItemView.onOpen()` via `template(this.contentEl)`. If it uses `boundary()` /
+async components, add `@arrow-js/framework` to the plugin and the side-effect
+`import '@arrow-js/framework'`. Leave sandbox chrome (`src/sandbox/*`) behind.