inkspan 0.0.0-stage → 0.1.0-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) Farming Labs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,90 @@
1
- # Temporary Holding Version
1
+ # Inkspan
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Index Markdown sections, MDX components, and fenced code with exact source ranges.**
4
+
5
+ Inkspan is a synchronous ESM library with a Rust WebAssembly engine for Node and a bundled JavaScript parser for browsers and edge runtimes. The package has zero runtime npm dependencies. It reads authored source. Rendering MDX and executing its JavaScript are outside its scope.
6
+
7
+ ## Install
8
+
9
+ Install the beta from npm:
10
+
11
+ ```sh
12
+ npm install inkspan@beta
13
+ ```
14
+
15
+ Versions through `0.1.0-beta.3` were published as `@farming-labs/inkspan`. To migrate, replace that name with `inkspan` in `package.json` and imports. The API is the same.
16
+
17
+ The package includes the built engine, parser, and TypeScript declarations. Installation requires Node 20 or later and works with lifecycle scripts disabled.
18
+
19
+ ## Find sections
20
+
21
+ ```js
22
+ import { parseMarkdownSections } from "inkspan";
23
+
24
+ const source = "# Guide\n\n## Install\nRun npm install.\n\n# Reference";
25
+ const [, install] = parseMarkdownSections(source);
26
+ console.log(install.title); // Install
27
+ console.log(install.startLine); // 3
28
+ console.log(install.endLine); // 5
29
+ console.log(install.content); // "## Install\nRun npm install.\n\n"
30
+ ```
31
+
32
+ Sections include their nested subsections. Lines are 1-based and inclusive. Source slices retain whitespace and line endings. Pass the body when your application handles frontmatter separately. Use `{ format: "mdx", ignoreElements: ["ExampleSource"] }` to skip headings inside example components. For custom anchors, `parseMarkdownOutline(source, options)` returns heading nodes and reference definitions in document order.
33
+
34
+ ## Find components, code, and text
35
+
36
+ ```js
37
+ import { indexMarkdown } from "inkspan";
38
+
39
+ const source = "# Demo 🌱\n\n<Example>Copy me.</Example>";
40
+ const { components } = indexMarkdown(source, {
41
+ format: "mdx",
42
+ components: ["Example"],
43
+ });
44
+ const [example] = components;
45
+ console.log(source.slice(example.start, example.end)); // <Example>Copy me.</Example>
46
+ ```
47
+
48
+ | Selection | Result |
49
+ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
50
+ | `components: true` or an array of names | Complete named Markdown-level JSX elements in source order. Offsets are half-open UTF-16 positions for JavaScript's `slice`. JavaScript expressions and ESM are opaque. |
51
+ | `codeBlocks: true` | Fenced code with source offsets, inclusive line numbers, language, metadata, and parsed code. |
52
+ | `text: true` | Readable text, including inline code, image alt text, and text inside Markdown-level components. Block code is omitted. Use `text: { includeCode: true }` to include it. |
53
+
54
+ With no selections, all three are returned. With explicit selections, unselected arrays are empty and unselected text is absent. The default format is GitHub Flavored Markdown. Use `format: "mdx"` for JSX. Invalid MDX throws `MarkdownSyntaxError` with code `ERR_MARKDOWN_SYNTAX` and the parser diagnostic in `cause`.
55
+
56
+ ## Opt into browser Wasm
57
+
58
+ The browser default uses JavaScript. For sustained structural indexing, the experimental browser entry can initialize a separate Wasm parser:
59
+
60
+ ```js
61
+ import { createInkspan } from "inkspan/browser";
62
+
63
+ const parser = await createInkspan({ experimental: { wasm: true } });
64
+ try {
65
+ const sections = parser.parseMarkdownSections(source);
66
+ const index = parser.indexMarkdown(source, { format: "mdx", components: true });
67
+ } finally {
68
+ parser.dispose();
69
+ }
70
+ ```
71
+
72
+ Initialization is asynchronous; `parseMarkdownSections`, `parseMarkdownOutline`, and `indexMarkdown` stay synchronous. Each factory call owns an independent parser. `dispose()` is idempotent and releases that instance's engine references; later parsing throws `InkspanError` with code `ERR_INKSPAN_DISPOSED`. ESM code remains cached, and garbage collection is controlled by the runtime.
73
+
74
+ `createInkspan()`, `{ experimental: {} }`, and `{ experimental: { wasm: false } }` use JavaScript without initializing Wasm. Existing root imports keep their current defaults. The Wasm loader and compressed bytes load through a dynamic import; enable ESM code splitting in your bundler to defer that chunk's download. The package has no separate Wasm URL to configure and adds no runtime npm dependencies.
75
+
76
+ The opt-in needs WebAssembly and browser APIs including [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream). A site's Content Security Policy must permit Wasm compilation. Initialization failures reject with `InkspanError`, code `ERR_INKSPAN_WASM_INIT`, and the original error in `cause`; they never silently select JavaScript. After fixing an engine initialization failure, call `createInkspan()` again. Reload the page after CSP changes or a failed module download cached by the browser. To explicitly choose JavaScript, omit the flag or set it to `false`. Invalid factory options reject with `ERR_INKSPAN_OPTIONS`.
77
+
78
+ Complex MDX and readable text still use the bundled JavaScript parser, preserving syntax diagnostics and `MarkdownSyntaxError` identity. Wasm is intended for repeated structural work, not an unconditional speed improvement. Edge runtimes retain their current JavaScript default; this opt-in is not an edge deployment compatibility claim. [Design and verification](./docs/browser-wasm.md).
79
+
80
+ ## Performance and development
81
+
82
+ On the 53-page Farming Labs corpus, section extraction was **4.18× faster on human pages** and **4.03× faster on agent sidecars** than the portable JavaScript implementation. The measured small JSX expression took 21.3 ms on Node and 12.9 ms with the portable parser. [Benchmark results and reproduction](https://github.com/farming-labs/inkspan/blob/main/docs/benchmarks.md).
83
+
84
+ Node uses Rust for eligible outlines, components, and fences. Complex syntax and readable-text requests use the reference parser. A small literal heading can return before Wasm initialization. Default browser and edge imports use the portable parser.
85
+
86
+ Run a cold-process comparison on your own corpus with `node benchmark/corpus.mjs ./content sections` or `node benchmark/corpus.mjs ./content components`. Both run nine samples after a warmup, alternate order, compare the full output, and report median, p95, and an independent baseline control. The output reports syntax errors for locally extended dialects.
87
+
88
+ Run `pnpm install --frozen-lockfile` and `pnpm test` for the Node and portable test suites. Run `node benchmark/check-parity.mjs` for differential fixtures. Pass a CommonMark specification JSON file for the extended suite. Use `pnpm build:reference` to rebuild the bundled parser. To rebuild Wasm, install Rust 1.99.1 with the `wasm32-unknown-unknown` target and `wasm-bindgen-cli` 0.2.128, then run `pnpm build:wasm`.
89
+
90
+ Maintainers can follow the [npm publishing guide](docs/publishing.md) to configure trusted publishing and release a tested tarball.
package/browser.d.ts ADDED
@@ -0,0 +1,31 @@
1
+ import type { parseMarkdownOutline, parseMarkdownSections, indexMarkdown } from "./index.js";
2
+
3
+ export { MarkdownSyntaxError } from "./index.js";
4
+
5
+ export interface InkspanOptions {
6
+ experimental?: {
7
+ /** Opt into browser Wasm initialization. Omitted or false uses JavaScript. */
8
+ wasm?: boolean;
9
+ };
10
+ }
11
+
12
+ export interface Inkspan {
13
+ parseMarkdownOutline: typeof parseMarkdownOutline;
14
+ parseMarkdownSections: typeof parseMarkdownSections;
15
+ indexMarkdown: typeof indexMarkdown;
16
+ /** Release this instance's engine references. Idempotent; later parsing throws. */
17
+ dispose(): void;
18
+ }
19
+
20
+ export type InkspanErrorCode =
21
+ | "ERR_INKSPAN_OPTIONS"
22
+ | "ERR_INKSPAN_WASM_INIT"
23
+ | "ERR_INKSPAN_DISPOSED";
24
+
25
+ export class InkspanError extends Error {
26
+ constructor(code: InkspanErrorCode, message: string, options?: { cause?: unknown });
27
+ readonly code: InkspanErrorCode;
28
+ }
29
+
30
+ /** Initialize once, then parse synchronously. Each call creates an independent instance. */
31
+ export function createInkspan(options?: InkspanOptions): Promise<Inkspan>;
package/browser.js ADDED
@@ -0,0 +1,86 @@
1
+ import { createMarkdownApi } from "./lib/core.js";
2
+ import * as portable from "./lib/portable.js";
3
+
4
+ export { MarkdownSyntaxError } from "./lib/core.js";
5
+
6
+ export class InkspanError extends Error {
7
+ constructor(code, message, options) {
8
+ super(message, options);
9
+ this.name = "InkspanError";
10
+ this.code = code;
11
+ }
12
+ }
13
+
14
+ function record(value) {
15
+ return (
16
+ value !== null &&
17
+ typeof value === "object" &&
18
+ (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
19
+ );
20
+ }
21
+
22
+ function wasmEnabled(options) {
23
+ const issues = [];
24
+ if (!record(options)) {
25
+ issues.push("Pass an options object to `createInkspan()`.");
26
+ } else {
27
+ for (const key of Object.keys(options)) {
28
+ if (key !== "experimental") issues.push(`Remove the unsupported option \`${key}\`.`);
29
+ }
30
+ if (options.experimental !== undefined) {
31
+ if (!record(options.experimental)) {
32
+ issues.push("Set `experimental` to an object containing `wasm`.");
33
+ } else {
34
+ for (const key of Object.keys(options.experimental)) {
35
+ if (key !== "wasm") issues.push(`Remove the unsupported option \`experimental.${key}\`.`);
36
+ }
37
+ if (
38
+ options.experimental.wasm !== undefined &&
39
+ typeof options.experimental.wasm !== "boolean"
40
+ ) {
41
+ issues.push("Set `experimental.wasm` to `true` or `false`.");
42
+ }
43
+ }
44
+ }
45
+ }
46
+ if (issues.length) {
47
+ const message = issues.join(" ");
48
+ throw new InkspanError("ERR_INKSPAN_OPTIONS", message, { cause: new TypeError(message) });
49
+ }
50
+ return options.experimental?.wasm === true;
51
+ }
52
+
53
+ export async function createInkspan(options = {}) {
54
+ let accelerator = portable;
55
+ if (wasmEnabled(options)) {
56
+ try {
57
+ const { createBrowserAccelerator } = await import("./lib/browser-wasm.js");
58
+ accelerator = await createBrowserAccelerator();
59
+ } catch (cause) {
60
+ throw new InkspanError(
61
+ "ERR_INKSPAN_WASM_INIT",
62
+ "Could not initialize browser Wasm. Check `cause` and browser permissions, then retry `createInkspan()`, or set `experimental.wasm` to `false`.",
63
+ { cause },
64
+ );
65
+ }
66
+ }
67
+ let api = createMarkdownApi(accelerator);
68
+ function active() {
69
+ if (api === null) {
70
+ throw new InkspanError(
71
+ "ERR_INKSPAN_DISPOSED",
72
+ "This Inkspan instance was disposed. Call `createInkspan()` to create another parser.",
73
+ );
74
+ }
75
+ return api;
76
+ }
77
+ return {
78
+ parseMarkdownOutline: (source, options) => active().parseMarkdownOutline(source, options),
79
+ parseMarkdownSections: (source, options) => active().parseMarkdownSections(source, options),
80
+ indexMarkdown: (source, options) => active().indexMarkdown(source, options),
81
+ dispose() {
82
+ api = null;
83
+ accelerator = null;
84
+ },
85
+ };
86
+ }