@weave-md/core - npm Package Compare versions

Comparing version 0.2.0-alpha.0 to 0.3.0-alpha.0

dist/nodeUrl/index.js

@@ -24,7 +24,7 @@ export function parseNodeUrl(href) {
             if (display) {
-                if (['footnote', 'sidenote', 'margin', 'overlay', 'inline', 'stretch', 'page'].includes(display)) {
+                if (['footnote', 'sidenote', 'margin', 'overlay', 'inline', 'stretch', 'panel'].includes(display)) {
                     ref.display = display;
                 }
                 else {
-                    return { success: false, error: `Invalid display value: ${display}. Must be one of: footnote, sidenote, margin, overlay, inline, stretch, page` };
+                    return { success: false, error: `Invalid display value: ${display}. Must be one of: footnote, sidenote, margin, overlay, inline, stretch, panel` };
                 }
@@ -31,0 +31,0 @@ }

dist/types/extended.d.ts

@@ -6,3 +6,3 @@ export interface ImageBlock {
     caption?: string;
-    width?: 'normal' | 'wide' | 'full';
+    width?: string;
 }
@@ -41,8 +41,22 @@ export interface GalleryBlock {
     type: 'math';
-    content: string;
+    value: string;
 }
 export interface PreBlock {
     type: 'pre';
-    content: string;
+    value: string;
 }
+export interface InlineMath {
+    type: 'inlineMath';
+    value: string;
+}
+export interface Sub {
+    type: 'sub';
+    children: unknown[];
+    data: {
+        replacement: unknown[];
+        rawInitial: string;
+        rawReplacement: string;
+    };
+}
 export type ExtendedBlock = ImageBlock | GalleryBlock | AudioBlock | VideoBlock | EmbedBlock | VoiceoverBlock | MathBlock | PreBlock;
+export type InlineExtension = InlineMath | Sub;

dist/types/index.d.ts

@@ -7,3 +7,3 @@ export interface Section {
 }
-export type DisplayType = 'footnote' | 'sidenote' | 'margin' | 'overlay' | 'inline' | 'stretch' | 'page';
+export type DisplayType = 'footnote' | 'sidenote' | 'margin' | 'overlay' | 'inline' | 'stretch' | 'panel';
 export type ExportHint = 'appendix' | 'inline' | 'omit';
@@ -10,0 +10,0 @@ export interface NodeRef {

package.json

 {
   "name": "@weave-md/core",
-  "version": "0.2.0-alpha.0",
+  "version": "0.3.0-alpha.0",
   "description": "Weave Markdown language contract - spec, schemas, types, and pure helpers",
@@ -24,2 +24,5 @@ "type": "module",
   },
+  "scripts": {
+    "build": "tsc"
+  },
   "keywords": [
@@ -41,6 +44,3 @@ "weave",
     "typescript": "^5.7.0"
-  },
-  "scripts": {
-    "build": "tsc"
   }
-}
+}

schema/weave-ast.schema.json

@@ -43,8 +43,2 @@ {
         },
-        "extendedBlocks": {
-          "type": "array",
-          "items": {
-            "$ref": "https://weave-md.org/schema/weave-format.schema.json#/definitions/ExtendedBlock"
-          }
-        },
         "position": {
@@ -73,3 +67,3 @@ "$ref": "#/definitions/SourcePosition",
       "type": "object",
-      "description": "A node link occurrence with start and end positions.",
+      "description": "A node link occurrence. Position fields (start/end) are optional and may be stripped for conformance output.",
       "properties": {
@@ -96,3 +90,3 @@ "ref": {
       },
-      "required": ["ref", "sourceId", "start", "end", "text"]
+      "required": ["ref", "sourceId", "text"]
     },
@@ -108,3 +102,3 @@ "NodeRef": {
           "type": "string",
-          "enum": ["footnote", "sidenote", "margin", "overlay", "inline", "stretch", "page"]
+          "enum": ["footnote", "sidenote", "margin", "overlay", "inline", "stretch", "panel"]
         },
@@ -111,0 +105,0 @@ "export": {

schema/weave-format.schema.json

@@ -5,11 +5,8 @@ {
   "title": "Weave Format Schema",
-  "description": "Schema definition for Weave format elements including blocks, inlines, and extended syntax",
+  "description": "Schema definition for Weave format elements. Block schemas (ImageBlock, etc.) define the structure of YAML content in fenced code blocks. Inline schemas (InlineMath, Sub) define mdast node structures produced by the parser.",
   "definitions": {
     "ImageBlock": {
       "type": "object",
+      "description": "YAML content for ```image blocks",
       "properties": {
-        "type": {
-          "type": "string",
-          "const": "image"
-        },
         "file": {
@@ -27,6 +24,6 @@ "type": "string",
           "type": "string",
-          "enum": ["normal", "wide", "full"]
+          "description": "Display width hint. Common values: normal, wide, full. Implementations MAY accept any string."
         }
       },
-      "required": ["type", "file"],
+      "required": ["file"],
       "additionalProperties": true
@@ -36,7 +33,4 @@ },
       "type": "object",
+      "description": "YAML content for ```gallery blocks",
       "properties": {
-        "type": {
-          "type": "string",
-          "const": "gallery"
-        },
         "files": {
@@ -57,3 +51,3 @@ "type": "array",
       },
-      "required": ["type", "files"],
+      "required": ["files"],
       "additionalProperties": true
@@ -63,7 +57,4 @@ },
       "type": "object",
+      "description": "YAML content for ```audio blocks",
       "properties": {
-        "type": {
-          "type": "string",
-          "const": "audio"
-        },
         "file": {
@@ -86,3 +77,3 @@ "type": "string",
       },
-      "required": ["type", "file"],
+      "required": ["file"],
       "additionalProperties": true
@@ -92,7 +83,4 @@ },
       "type": "object",
+      "description": "YAML content for ```video blocks",
       "properties": {
-        "type": {
-          "type": "string",
-          "const": "video"
-        },
         "file": {
@@ -124,3 +112,3 @@ "type": "string",
       },
-      "required": ["type", "file"],
+      "required": ["file"],
       "additionalProperties": true
@@ -130,7 +118,4 @@ },
       "type": "object",
+      "description": "YAML content for ```embed blocks",
       "properties": {
-        "type": {
-          "type": "string",
-          "const": "embed"
-        },
         "url": {
@@ -141,3 +126,3 @@ "type": "string",
       },
-      "required": ["type", "url"],
+      "required": ["url"],
       "additionalProperties": true
@@ -147,7 +132,4 @@ },
       "type": "object",
+      "description": "YAML content for ```voiceover blocks",
       "properties": {
-        "type": {
-          "type": "string",
-          "const": "voiceover"
-        },
         "file": {
@@ -158,3 +140,3 @@ "type": "string",
       },
-      "required": ["type", "file"],
+      "required": ["file"],
       "additionalProperties": true
@@ -164,13 +146,10 @@ },
       "type": "object",
-      "description": "Block math using ```math fenced code block",
+      "description": "Content for ```math blocks (raw LaTeX, no YAML)",
       "properties": {
-        "type": {
+        "value": {
           "type": "string",
-          "const": "math"
-        },
-        "content": {
-          "type": "string"
+          "description": "The LaTeX math content"
         }
       },
-      "required": ["type", "content"]
+      "required": ["value"]
     },
@@ -185,138 +164,52 @@ "InlineMath": {
         },
-        "content": {
-          "type": "string"
-        }
-      },
-      "required": ["type", "content"]
-    },
-    "PreBlock": {
-      "type": "object",
-      "properties": {
-        "type": {
+        "value": {
           "type": "string",
-          "const": "pre"
-        },
-        "content": {
-          "type": "string"
+          "description": "The math expression content (uses 'value' per mdast convention)"
         }
       },
-      "required": ["type", "content"]
+      "required": ["type", "value"]
     },
-    "Strikethrough": {
+    "Sub": {
       "type": "object",
-      "description": "Inline strikethrough text using ~~text~~ syntax",
+      "description": "Inline substitution using :sub[INITIAL]{REPLACEMENT} syntax",
       "properties": {
         "type": {
           "type": "string",
-          "const": "strikethrough"
+          "const": "sub"
         },
-        "content": {
-          "type": "string"
-        }
-      },
-      "required": ["type", "content"]
-    },
-    "TableCell": {
-      "type": "object",
-      "properties": {
-        "content": {
-          "type": "string"
+        "children": {
+          "description": "Initial content as mdast phrasing nodes (empty array from mdast-util-substitute)",
+          "type": "array"
         },
-        "align": {
-          "type": "string",
-          "enum": ["left", "center", "right"],
-          "description": "Cell alignment inherited from column definition"
-        }
-      },
-      "required": ["content"]
-    },
-    "TableRow": {
-      "type": "object",
-      "properties": {
-        "cells": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/TableCell"
-          }
-        }
-      },
-      "required": ["cells"]
-    },
-    "Table": {
-      "type": "object",
-      "description": "GFM-style table with headers and optional column alignment",
-      "properties": {
-        "type": {
-          "type": "string",
-          "const": "table"
-        },
-        "header": {
-          "$ref": "#/definitions/TableRow",
-          "description": "Header row defining column names"
-        },
-        "align": {
-          "type": "array",
-          "items": {
-            "type": ["string", "null"],
-            "enum": ["left", "center", "right", null]
+        "data": {
+          "type": "object",
+          "properties": {
+            "replacement": {
+              "description": "Replacement content as mdast phrasing nodes (empty array from mdast-util-substitute)",
+              "type": "array"
+            },
+            "rawInitial": {
+              "description": "Raw initial text",
+              "type": "string"
+            },
+            "rawReplacement": {
+              "description": "Raw replacement text",
+              "type": "string"
+            }
           },
-          "description": "Column alignments from the delimiter row"
-        },
-        "rows": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/TableRow"
-          },
-          "description": "Data rows"
+          "required": ["replacement", "rawInitial", "rawReplacement"]
         }
       },
-      "required": ["type", "header", "rows"]
+      "required": ["type", "children", "data"]
     },
-    "AutolinkLiteral": {
+    "PreBlock": {
       "type": "object",
-      "description": "Auto-linked URL or email address",
+      "description": "Content for ```pre blocks (raw text, no YAML)",
       "properties": {
-        "type": {
+        "value": {
           "type": "string",
-          "const": "autolink"
-        },
-        "linkType": {
-          "type": "string",
-          "enum": ["url", "email"],
-          "description": "Whether this is a URL or email autolink"
-        },
-        "url": {
-          "type": "string",
-          "format": "uri",
-          "description": "Present when linkType is 'url'"
-        },
-        "email": {
-          "type": "string",
-          "format": "email",
-          "description": "Present when linkType is 'email'"
+          "description": "The preformatted text content"
         }
       },
-      "required": ["type", "linkType"],
-      "allOf": [
-        {
-          "if": {
-            "properties": { "linkType": { "const": "url" } },
-            "required": ["linkType"]
-          },
-          "then": {
-            "required": ["url"],
-            "not": { "required": ["email"] }
-          }
-        },
-        {
-          "if": {
-            "properties": { "linkType": { "const": "email" } },
-            "required": ["linkType"]
-          },
-          "then": {
-            "required": ["email"],
-            "not": { "required": ["url"] }
-          }
-        }
-      ]
+      "required": ["value"]
     },
@@ -332,4 +225,3 @@ "ExtendedBlock": {
         { "$ref": "#/definitions/MathBlock" },
-        { "$ref": "#/definitions/PreBlock" },
-        { "$ref": "#/definitions/Table" }
+        { "$ref": "#/definitions/PreBlock" }
       ]
@@ -339,5 +231,4 @@ },
       "oneOf": [
-        { "$ref": "#/definitions/Strikethrough" },
-        { "$ref": "#/definitions/AutolinkLiteral" },
-        { "$ref": "#/definitions/InlineMath" }
+        { "$ref": "#/definitions/InlineMath" },
+        { "$ref": "#/definitions/Sub" }
       ]
@@ -344,0 +235,0 @@ }

spec/conformance.md

@@ -41,2 +41,3 @@ # Conformance Testing
 - Parse Weave Format blocks (math, gallery, audio, video, etc.)
+- Parse inline extensions (`:math[...]`, `:sub[...]{...}`)
 - Preserve content and parameters in AST
@@ -43,0 +44,0 @@ - Render appropriately when supported

spec/node-links.md

@@ -43,3 +43,3 @@ # Node Links — Full Overview
 - If interaction is required and `[ ]` is used, the **renderer MUST supply an affordance**.
-- Numbering is **semantic and system-assigned**, never authored.
+- Sequence markers are **semantic and system-assigned**, never authored.
 - Renderers MUST NOT render the space in `[ ]`.
@@ -52,3 +52,3 @@ - Empty `[]` is not valid CommonMark and MUST NOT be used unless explicitly supported as a parser extension.
 
-**Numbered reference optionally rendered at the bottom.**
+**Ordered reference, *optionally* rendered at the bottom.**
 
@@ -60,4 +60,4 @@ ```md
 
-- Always numbered
-- Text-linked form appends the number to the text
+- Always ordered
+- Text-linked form appends the sequence marker to the text
 - Hover/click preview optional
@@ -69,3 +69,3 @@
 
-**Numbered reference rendered in the margin.**
+**Ordered reference rendered in the margin.**
 
@@ -77,6 +77,6 @@ ```md
 
-- Always numbered
+- Always ordered
 - Margin placement on desktop
 - Click may highlight anchor location
-- Mobile fallback: overlay
+- Mobile fallback required
 
@@ -87,3 +87,3 @@ ---
 
-**Unnumbered annotation rendered in the margin.**
+**Unordered annotation rendered in the margin.**
 
@@ -95,5 +95,5 @@ ```md
 
-- Never numbered
+- Never ordered
 - Anchor-only margin notes may render with no inline marker
-- Mobile fallback: inline at end of paragraph (unless disabled)
+- Mobile fallback required
 
@@ -143,21 +143,20 @@ ---
 - Renderer must supply an affordance for anchor-only references
-- Mobile UI may vary, semantics unchanged
+- Mobile fallback may be required
 
 ---
 
-## 7. Page Node
+## 7. Panel Node
 
-**Node resolved as a full page or section view.**
+**Content rendered in a persistent, dismissible view.**
 
 ```md
-[Read more](node:topic?display=page)
-[ ](node:topic?display=page)
+[Read more](node:topic?display=panel)
+[ ](node:topic?display=panel)
 ```
 
-- Renderer must supply a navigation affordance for anchor-only references
-- May open as:
-  - stacked / overlay page (Gwern-style)
-  - same tab
-  - new tab
-- Semantics are “resolve as page,” not “navigate away”
+- No browser navigation — content appears on the current page
+- View persists until explicitly dismissed or collapsed
+- Size and presentation are renderer-defined
+- Renderer must supply an affordance for anchor-only references
+- Mobile fallback required
 
@@ -168,11 +167,11 @@ ---
 
-| Display | Numbered | Anchor-only behavior (`[ ]`) | Primary Placement / Behavior |
+| Display | Ordered | Anchor-only behavior (`[ ]`) | Primary Placement / Behavior |
 |---------|----------|------------------------------|------------------------------|
-| footnote | yes | Renderer renders number marker | Bottom/end footnote |
-| sidenote | yes | Renderer renders number marker | Margin note (fallback overlay) |
-| margin | no | Renderer only creates margin note | Margin note (fallback inline) |
+| footnote | yes | Renderer renders sequence marker | Bottom/end footnote |
+| sidenote | yes | Renderer renders sequence marker | Margin note |
+| margin | no | Renderer only creates margin note | Margin note |
 | overlay | no | Renderer supplies trigger | Floating layer |
 | inline | no | Renderer supplies expander | In-flow expandable block |
 | stretch | no | Renderer supplies expander | Nested expandable block |
-| page | no | Renderer supplies navigation | Page / stacked page view |
+| panel | no | Renderer supplies affordance | Persistent section view |
 
@@ -179,0 +178,0 @@ ---

spec/weave-format.md

@@ -98,2 +98,17 @@ # Weave Format
 
+### Inline Substitution
+
+Use the `:sub[INITIAL]{REPLACEMENT}` syntax for inline substitution:
+
+```markdown
+The :sub[TL;DR]{full explanation that appears after activation} summarizes the point.
+```
+
+**Behavior**:
+- Initially renders `INITIAL`; on activation, replaces the span with `REPLACEMENT`
+- After activation, the element is no longer interactive (one-way)
+- Nested `:sub` inside `REPLACEMENT` is allowed
+
+**Note (Non-Normative)**: Implementations MAY allow collapsing a revealed `:sub` back to its initial state as a UI convenience.
+
 ## Media Elements
@@ -117,3 +132,3 @@
 
-Image Fields:
+**Image Fields**:
 - `file` (required) — Image URL or file reference
@@ -124,3 +139,3 @@ - `alt` — Alternative text for accessibility (optional)
 
-Behavior:
+**Behavior**:
 - Renders as a semantic image block
@@ -145,3 +160,3 @@ - If caption is present, it SHOULD be rendered as a caption
 
-Gallery Fields:
+**Gallery Fields**:
 - `files` (required) — List of image URLs or file references (MUST contain at least one entry)
@@ -151,3 +166,3 @@ - `alt` — Alternative text describing the gallery as a whole (optional)
 
-Behavior:
+**Behavior**:
 - Renders as a grouped visual unit
@@ -170,3 +185,3 @@ - Layout (grid, carousel, etc.) is implementation-defined
 
-Audio Fields:
+**Audio Fields**:
 - `file` (required) — Audio file URL or file reference
@@ -192,3 +207,3 @@ - `autoplay` — Auto-play on load (optional, default: false)
 
-Video Fields:
+**Video Fields**:
 - `file` (required) — Video file URL or file reference
@@ -211,6 +226,6 @@ - `poster` — Thumbnail image URL (optional)
 
-Embed Fields:
+**Embed Fields**:
 - `url` (required) — URL of the content to embed
 
-Behavior:
+**Behavior**:
 - Creates an iframe or appropriate embed container for the URL
@@ -228,6 +243,6 @@
 
-Voiceover Fields:
+**Voiceover Fields**:
 - `file` (required) — Audio file URL or file reference for the voiceover
 
-Behavior:
+**Behavior**:
 - Embeds pre-recorded voiceover audio narration

LICENSE

-MIT License
-
-Copyright (c) 2025 weavepage
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

No alert changes

Worsened metrics

Total package byte prevSize

40806

-5.42%

Number of package files

22

-4.35%

Lines of code

672

-13.07%

No dependency changes