@tarhnama/core 0.1.0

package/dist/tree.js

@@ -0,0 +1,190 @@
+import { BODY } from './types.js';
+/**
+ * Build the derived tree in a single O(n) pass.
+ *
+ * The rule that makes body text work: a level-0 block attaches to the nearest open
+ * heading but NEVER terminates a subtree. Only a heading whose level is <= an open
+ * heading's level closes it. This mirrors Word's outline semantics, where body text
+ * under "1.2" stays under "1.2" no matter how much of it there is.
+ *
+ * (The legacy `Document.getDirectChildren` had a bug here: it broke on `level <= own`
+ * without excluding body text, so a heading's direct children were truncated at the
+ * first paragraph of body text. That bug is not reproduced — see the regression test.)
+ */
+export function buildIndex(blocks) {
+    const n = blocks.length;
+    const parent = new Int32Array(n).fill(-1);
+    const subtreeEnd = new Int32Array(n);
+    const depth = new Int32Array(n);
+    // Stack of indices of currently-open headings, strictly increasing in level.
+    const open = [];
+    for (let i = 0; i < n; i++) {
+        const level = blocks[i].level;
+        if (level === BODY) {
+            // Body text: attaches to the enclosing heading, closes nothing.
+            const top = open.length > 0 ? open[open.length - 1] : -1;
+            parent[i] = top;
+            subtreeEnd[i] = i + 1;
+            depth[i] = top === -1 ? 0 : depth[top] + 1;
+            continue;
+        }
+        // A heading closes every open heading at the same or deeper level.
+        while (open.length > 0 && blocks[open[open.length - 1]].level >= level) {
+            subtreeEnd[open.pop()] = i;
+        }
+        const top = open.length > 0 ? open[open.length - 1] : -1;
+        parent[i] = top;
+        depth[i] = top === -1 ? 0 : depth[top] + 1;
+        open.push(i);
+    }
+    // Headings still open at EOF extend to the end of the document.
+    while (open.length > 0)
+        subtreeEnd[open.pop()] = n;
+    return { parent, subtreeEnd, depth, length: n };
+}
+/** `[start, end)` covering `i` and everything beneath it. */
+export function subtreeRange(index, i) {
+    return [i, index.subtreeEnd[i]];
+}
+/** Every descendant index of `i`, at any depth, in document order. */
+export function deepChildren(index, i) {
+    const out = [];
+    for (let j = i + 1; j < index.subtreeEnd[i]; j++)
+        out.push(j);
+    return out;
+}
+/** Heading children of `i` — one level down in the DERIVED tree, not by `level`. */
+export function childHeadings(blocks, index, i) {
+    const out = [];
+    for (let j = i + 1; j < index.subtreeEnd[i]; j++) {
+        if (index.parent[j] === i && blocks[j].level !== BODY)
+            out.push(j);
+    }
+    return out;
+}
+/** Body-text blocks belonging directly to `i`. */
+export function bodyChildren(blocks, index, i) {
+    const out = [];
+    for (let j = i + 1; j < index.subtreeEnd[i]; j++) {
+        if (index.parent[j] === i && blocks[j].level === BODY)
+            out.push(j);
+    }
+    return out;
+}
+/** Chain of ancestors from nearest parent to root. */
+export function ancestors(index, i) {
+    const out = [];
+    for (let p = index.parent[i]; p !== -1; p = index.parent[p])
+        out.push(p);
+    return out;
+}
+/**
+ * Whether two block lists have the same STRUCTURE: the same blocks, at the same levels,
+ * folded and locked the same way. Text is not structure.
+ *
+ * Everything a view derives from the outline — the tree, the counts, the folds, the locks,
+ * the spine — depends on exactly these fields, and typing never changes one. A memo keyed
+ * on the LIST recomputes per character, because every edit makes a new list; keyed on this
+ * it recomputes when the outline actually moves. The `a === b` check is the fast path:
+ * structural ops share unchanged blocks by reference, and so does the editor's conversion,
+ * so for typing this is a pointer comparison per block.
+ */
+export function sameStructure(a, b) {
+    if (a === b)
+        return true;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        if (x === y)
+            continue;
+        if (x.id !== y.id || x.level !== y.level)
+            return false;
+        if ((x.collapsed === true) !== (y.collapsed === true))
+            return false;
+        if ((x.locked === true) !== (y.locked === true))
+            return false;
+    }
+    return true;
+}
+export function hasChildren(index, i) {
+    return index.subtreeEnd[i] > i + 1;
+}
+/** Index of the nearest preceding heading, or -1. Used by the indent rules. */
+export function prevHeading(blocks, i) {
+    for (let j = i - 1; j >= 0; j--)
+        if (blocks[j].level !== BODY)
+            return j;
+    return -1;
+}
+/**
+ * Indices that should actually be rendered, honouring `collapsed`.
+ *
+ * This is the project's primary scale lever. ProseMirror puts the entire document
+ * in the DOM and cannot be virtualized, so the working set has to be small by
+ * construction — and an outline collapsed to level 2 renders hundreds of blocks
+ * rather than tens of thousands. A collapsed subtree must render as NOTHING, not
+ * as hidden DOM, or the lever does no work.
+ */
+export function visibleIndices(blocks, index) {
+    const out = [];
+    for (let i = 0; i < blocks.length;) {
+        out.push(i);
+        if (blocks[i].collapsed && index.subtreeEnd[i] > i + 1) {
+            i = index.subtreeEnd[i]; // skip the whole subtree
+        }
+        else {
+            i++;
+        }
+    }
+    return out;
+}
+/** Convenience for callers that want blocks rather than indices. */
+export function visibleBlocks(blocks, index) {
+    return visibleIndices(blocks, index).map((i) => blocks[i]);
+}
+/**
+ * Is `i` read-only — either locked itself, or inside a locked subtree?
+ *
+ * Walks ancestors rather than reading a stored flag, which is what keeps lock state
+ * correct for free when a block is moved, indented, or outdented: a block dragged out
+ * of a locked chapter stops being locked because its ancestry changed, with no
+ * bookkeeping pass to get wrong.
+ */
+export function isLocked(blocks, index, i) {
+    const block = blocks[i];
+    if (!block)
+        return false;
+    if (block.locked === true)
+        return true;
+    for (const ancestor of ancestors(index, i)) {
+        if (blocks[ancestor]?.locked === true)
+            return true;
+    }
+    return false;
+}
+/**
+ * The nearest ancestor (or self) that carries the lock, or -1.
+ *
+ * The UI needs this to say WHAT is locked — "this chapter is read-only" is actionable,
+ * "this paragraph is read-only" leaves the reader hunting for the padlock.
+ */
+export function lockOwner(blocks, index, i) {
+    if (blocks[i]?.locked === true)
+        return i;
+    for (const ancestor of [...ancestors(index, i)].reverse()) {
+        if (blocks[ancestor]?.locked === true)
+            return ancestor;
+    }
+    return -1;
+}
+/** Indices of every read-only block, for bulk checks like a paste guard. */
+export function lockedIndices(blocks, index) {
+    const out = [];
+    for (let i = 0; i < blocks.length; i++)
+        if (isLocked(blocks, index, i))
+            out.push(i);
+    return out;
+}
+//# sourceMappingURL=tree.js.map

package/dist/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,239 @@
+/**
+ * The canonical outline model: a FLAT list of blocks, each carrying an explicit
+ * outline level. The tree is DERIVED (see tree.ts), never stored.
+ *
+ * Why flat: Microsoft Word is flat (`w:outlineLvl` per paragraph) and Markdown is
+ * flat (`#`..`######`). Critically, real Word documents skip levels (an H1 followed
+ * by an H3) all the time — a nested schema cannot represent that and rejects the
+ * document on import. A flat model imports it and normalizes on demand.
+ */
+/**
+ * `0` is body text and is NOT a hierarchy level — body text belongs to the nearest
+ * preceding heading. `1`-`9` are outline levels.
+ *
+ * Note the off-by-one against OOXML: Word's `w:outlineLvl` is 0-indexed (0-8),
+ * so `outlineLvl + 1 === OutlineLevel` for headings. Getting this wrong silently
+ * corrupts every imported document, so the conversion lives in exactly one place
+ * (see @tarhnama/docx) and is tested.
+ */
+export type OutlineLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+/** Body text: belongs to the nearest preceding heading, terminates no subtree. */
+export declare const BODY: 0;
+/** The deepest addressable outline level, matching Word's Heading 1-9. */
+export declare const MAX_LEVEL: 9;
+/**
+ * Per-block text direction. Persian-first: `rtl` is the default. `auto` defers to
+ * first-strong-character detection.
+ *
+ * This is a per-block attribute rather than a CSS concern because Word stores
+ * direction per paragraph (`w:bidi`), so a per-block attribute round-trips 1:1.
+ */
+export type Direction = 'rtl' | 'ltr' | 'auto';
+/**
+ * A single block. `content` is deliberately opaque: the core never interprets
+ * inline content, which keeps this package free of any editor dependency and
+ * lets the same tree algorithms serve the ProseMirror layer, the .docx importer,
+ * and any future engine.
+ */
+export interface Block<C = unknown> {
+    readonly id: string;
+    readonly level: OutlineLevel;
+    readonly type: string;
+    readonly dir: Direction;
+    readonly collapsed: boolean;
+    /**
+     * Read-only. A locked block's content cannot be edited and its position in the tree
+     * cannot change.
+     *
+     * Set only on the block the user actually locked — locking a heading locks its whole
+     * SUBTREE, but that is DERIVED (`isLocked`) rather than written onto every descendant.
+     * Storing it per-block would make lock state drift the moment a block moves, and would
+     * turn "lock this chapter" into an edit of every paragraph inside it.
+     *
+     * Collapse is deliberately still allowed on a locked subtree: collapsing is a view
+     * operation, not an edit, and a reader must be able to fold a section they cannot change.
+     */
+    readonly locked?: boolean;
+    /** Paragraph-level formatting (alignment, spacing, indent). See `BlockFormat`. */
+    readonly format?: BlockFormat;
+    /**
+     * The named style this block references (`w:pStyle`).
+     *
+     * Direct formatting in `format` OVERRIDES the style, exactly as in Word. A block with
+     * neither is the document's default style.
+     */
+    readonly styleId?: string;
+    readonly content?: C;
+    /**
+     * Per-type properties the core deliberately does NOT interpret: a code block's
+     * language, a list item's marker and depth, a blockquote's nesting. Word and Markdown
+     * both carry these, and without somewhere to put them an importer has to either drop
+     * them or smuggle them into `type`, which is worse.
+     *
+     * Opaque here for the same reason `content` is — core stays free of any format's
+     * vocabulary, and the tree algorithms never look at it.
+     */
+    readonly attrs?: Readonly<Record<string, unknown>>;
+}
+/** A flat document. */
+export type Blocks<C = unknown> = readonly Block<C>[];
+/**
+ * The derived tree, computed in one O(n) pass over the flat list.
+ *
+ * Every array is indexed by block position. Recomputing this on each transaction
+ * is cheap and keeps the flat list the single source of truth — no tree state to
+ * fall out of sync.
+ */
+export interface TreeIndex {
+    /** Index of the governing heading, or -1 for a top-level block. */
+    readonly parent: Int32Array;
+    /** Exclusive end index of this block's subtree. For body text, always `i + 1`. */
+    readonly subtreeEnd: Int32Array;
+    /** Depth in the derived tree. Differs from `level` when levels skip. */
+    readonly depth: Int32Array;
+    /** Number of blocks the index was built from. */
+    readonly length: number;
+}
+export declare function isHeading(block: Block): boolean;
+export declare function isBody(block: Block): boolean;
+/**
+ * Paragraph-level formatting — what Word keeps in `w:pPr`.
+ *
+ * Separate from `attrs` because it is universal: every block can carry it, every exporter
+ * needs it, and giving it a type means a typo in one package is a compile error rather
+ * than a silently missing indent.
+ *
+ * **Units are twips (1/20 of a point), matching Word exactly.** The same reasoning as
+ * half-points for font size: Word stores `w:spacing`/`w:ind` in twips, so storing anything
+ * else means rounding on every round trip, and rounding accumulates. Helpers convert for
+ * display.
+ */
+export interface BlockFormat {
+    /**
+     * LOGICAL alignment, not physical.
+     *
+     * `start`/`end` rather than `left`/`right` for the same reason the CSS is written with
+     * logical properties: in a Persian document `start` is the right-hand edge, and a
+     * model that stored `left` would mirror wrongly the moment direction changed.
+     */
+    readonly align?: 'start' | 'end' | 'center' | 'justify';
+    /** Line spacing as a multiple: 1 single, 1.5, 2 double. */
+    readonly lineHeight?: number;
+    readonly spaceBeforeTwips?: number;
+    readonly spaceAfterTwips?: number;
+    /** Indent from the start edge — the right in RTL. */
+    readonly indentStartTwips?: number;
+    readonly indentEndTwips?: number;
+    /** First-line indent. NEGATIVE means a hanging indent, as in Word. */
+    readonly firstLineTwips?: number;
+    /** Keep with the following paragraph when paginating. */
+    readonly keepNext?: boolean;
+    /** Do not split this paragraph across pages. */
+    readonly keepLines?: boolean;
+    readonly pageBreakBefore?: boolean;
+    /** Paragraph shading as `#RRGGBB`. */
+    readonly shading?: string;
+}
+/**
+ * A named paragraph style.
+ *
+ * Word documents are built out of these: a paragraph carries a style reference plus
+ * whatever direct formatting overrides it. Resolving styles down to direct formatting on
+ * import — which is what this project did until now — renders correctly and then loses
+ * the whole structure on the way back out. Word shows the result as "Normal + formatting"
+ * on every paragraph, the styles pane is empty, and the author's ability to restyle the
+ * document in one action is gone. The style name is content, not presentation.
+ *
+ * Kept in `core` rather than `docx` because Markdown and the editor both need to round-trip
+ * the reference even though neither interprets it.
+ */
+export interface NamedStyle {
+    /** `w:styleId` — the stable key a paragraph references. */
+    readonly id: string;
+    /** `w:name` — what the user sees in Word's styles pane. */
+    readonly name: string;
+    /**
+     * `w:basedOn`. Resolution walks this chain, so a cycle must be broken by the resolver
+     * rather than trusted not to exist — real documents contain them.
+     */
+    readonly basedOn?: string;
+    /** The outline level this style implies (`w:outlineLvl` + 1). */
+    readonly outlineLevel?: OutlineLevel;
+    readonly format?: BlockFormat;
+    /** Run-level defaults the style carries. Half-points, as Word stores them. */
+    readonly font?: string;
+    readonly sizeHalfPt?: number;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly color?: string;
+    /** True for Word's own styles (Normal, Heading 1–9), which must not be renamed. */
+    readonly builtIn?: boolean;
+}
+/**
+ * Page setup — Word's `w:sectPr`.
+ *
+ * Margins are LOGICAL (`start`/`end`), not `left`/`right`, for the same reason the rest of
+ * the model is: in an RTL document the binding edge is the right one, and a model storing
+ * `left` mirrors wrongly the instant direction changes. The conversion to Word's physical
+ * `w:left`/`w:right` happens once, in the exporter, where the section's direction is known.
+ */
+export interface PageSetup {
+    readonly widthTwips?: number;
+    readonly heightTwips?: number;
+    readonly marginTopTwips?: number;
+    readonly marginBottomTwips?: number;
+    readonly marginStartTwips?: number;
+    readonly marginEndTwips?: number;
+    /** `w:gutter` — extra space on the binding edge. */
+    readonly gutterTwips?: number;
+    /** `w:mirrorMargins` — swap start/end on facing pages, for double-sided printing. */
+    readonly mirrorMargins?: boolean;
+    /** `w:bidi` on the section: columns and margins run right-to-left. */
+    readonly rtl?: boolean;
+    readonly landscape?: boolean;
+}
+/** A4 in twips. Word's default for most of the world, and the one Persian documents use. */
+export declare const A4_WIDTH_TWIPS = 11906;
+export declare const A4_HEIGHT_TWIPS = 16838;
+/** Word's default margin: one inch. */
+export declare const DEFAULT_MARGIN_TWIPS = 1440;
+/** A4, RTL, one-inch margins — the sane default for a Persian document. */
+export declare const PERSIAN_A4: PageSetup;
+/** 1 point = 20 twips. Word's unit throughout `w:pPr`. */
+export declare const TWIPS_PER_POINT = 20;
+export declare function pointsToTwips(points: number): number;
+export declare function twipsToPoints(twips: number): number;
+/** Twips to a CSS length, for rendering. */
+export declare function twipsToCss(twips: number): string;
+/**
+ * A document: blocks plus the identity that links point at.
+ *
+ * First-class in the model rather than a concept each application reinvents. A link
+ * targets `docId`, the search index is keyed by it, and persistence stores it — so a
+ * "document" that only existed as an application's own interface meant every consumer
+ * had to agree on its shape by convention.
+ */
+export interface OutlineDocumentOf<C = unknown> {
+    readonly id: string;
+    readonly title: string;
+    readonly blocks: Blocks<C>;
+    /** Epoch millis of the last change, when the host tracks it. */
+    readonly updatedAt?: number;
+    /**
+     * Default direction for blocks that do not state one, and for empty blocks where
+     * first-strong detection has nothing to work with.
+     */
+    readonly dir?: Direction;
+    /**
+     * The document's style table. Blocks reference entries by `styleId`.
+     *
+     * On the document rather than global because two documents in one workspace legitimately
+     * carry different style definitions — they came from different Word files.
+     */
+    readonly styles?: readonly NamedStyle[];
+    /** Page geometry, for `.docx` export and print. */
+    readonly page?: PageSetup;
+    /** Host-defined metadata: tags, author, source path. Never interpreted here. */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,47 @@
+/**
+ * The canonical outline model: a FLAT list of blocks, each carrying an explicit
+ * outline level. The tree is DERIVED (see tree.ts), never stored.
+ *
+ * Why flat: Microsoft Word is flat (`w:outlineLvl` per paragraph) and Markdown is
+ * flat (`#`..`######`). Critically, real Word documents skip levels (an H1 followed
+ * by an H3) all the time — a nested schema cannot represent that and rejects the
+ * document on import. A flat model imports it and normalizes on demand.
+ */
+/** Body text: belongs to the nearest preceding heading, terminates no subtree. */
+export const BODY = 0;
+/** The deepest addressable outline level, matching Word's Heading 1-9. */
+export const MAX_LEVEL = 9;
+export function isHeading(block) {
+    return block.level >= 1;
+}
+export function isBody(block) {
+    return block.level === BODY;
+}
+/** A4 in twips. Word's default for most of the world, and the one Persian documents use. */
+export const A4_WIDTH_TWIPS = 11906;
+export const A4_HEIGHT_TWIPS = 16838;
+/** Word's default margin: one inch. */
+export const DEFAULT_MARGIN_TWIPS = 1440;
+/** A4, RTL, one-inch margins — the sane default for a Persian document. */
+export const PERSIAN_A4 = {
+    widthTwips: A4_WIDTH_TWIPS,
+    heightTwips: A4_HEIGHT_TWIPS,
+    marginTopTwips: DEFAULT_MARGIN_TWIPS,
+    marginBottomTwips: DEFAULT_MARGIN_TWIPS,
+    marginStartTwips: DEFAULT_MARGIN_TWIPS,
+    marginEndTwips: DEFAULT_MARGIN_TWIPS,
+    rtl: true,
+};
+/** 1 point = 20 twips. Word's unit throughout `w:pPr`. */
+export const TWIPS_PER_POINT = 20;
+export function pointsToTwips(points) {
+    return Math.round(points * TWIPS_PER_POINT);
+}
+export function twipsToPoints(twips) {
+    return twips / TWIPS_PER_POINT;
+}
+/** Twips to a CSS length, for rendering. */
+export function twipsToCss(twips) {
+    return `${twipsToPoints(twips)}pt`;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,kFAAkF;AAClF,MAAM,CAAC,MAAM,IAAI,GAAG,CAAU,CAAC;AAE/B,0EAA0E;AAC1E,MAAM,CAAC,MAAM,SAAS,GAAG,CAAU,CAAC;AA+EpC,MAAM,UAAU,SAAS,CAAC,KAAY;IACpC,OAAO,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAY;IACjC,OAAO,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC;AAC9B,CAAC;AAqGD,4FAA4F;AAC5F,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AACrC,uCAAuC;AACvC,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,UAAU,GAAc;IACnC,UAAU,EAAE,cAAc;IAC1B,WAAW,EAAE,eAAe;IAC5B,cAAc,EAAE,oBAAoB;IACpC,iBAAiB,EAAE,oBAAoB;IACvC,gBAAgB,EAAE,oBAAoB;IACtC,cAAc,EAAE,oBAAoB;IACpC,GAAG,EAAE,IAAI;CACV,CAAC;AAEF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAElC,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK,GAAG,eAAe,CAAC;AACjC,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC;AACrC,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tarhnama/core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic outline document model: flat blocks with outline levels, plus a derived tree index. No DOM, no editor dependency.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mahdi/tarhnama.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/mahdi/tarhnama#readme",
+  "bugs": "https://github.com/mahdi/tarhnama/issues",
+  "keywords": [
+    "outline",
+    "editor",
+    "rtl",
+    "persian",
+    "prosemirror",
+    "docx",
+    "markdown"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}