sdocs 0.0.43 → 0.0.45

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.45] - 2026-07-04
+
+### Fixed
+
+- **The sdoc grammar survives multi-block files.** The embedded Svelte
+  grammar opens a text region after any line ending in `>` that only closes
+  at the next `<` or `{` — it swallowed block closers, leaving everything
+  after the first `[preview]` uncolored. Block bodies now embed Svelte
+  behind line-guarded regions (the mechanism markdown fences use), so
+  closers, sibling blocks, and later entities all highlight correctly.
+
+## [0.0.44] - 2026-07-04
+
+### Changed
+
+- The README documents the block format — the npm listing previously showed
+  the retired `export const meta` convention.
+
 ## [0.0.43] - 2026-07-04
 
 ### Added

package/README.md

@@ -96,93 +96,80 @@ That's it — your docs page lives at `/docs` inside your existing app.
 
 ## Writing Docs
 
-sdocs supports three types of doc files:
+A `.sdoc` file is `<script>` at the top, entity blocks in the middle, and an
+optional `<style>` at the bottom. Every entity is its own sidebar entry, so
+one file can hold several.
 
-### Component Docs (`.sdoc`)
+### Component docs — `[DOCS]`
 
-Document a Svelte component with interactive controls and examples.
-
-```svelte
-<!-- Button.sdoc -->
+```sdoc
 <script lang="ts">
-  import Button from './Button.svelte';
-
-  export const meta = {
-    component: Button,
-    title: 'Components / Button',
-    description: 'A flexible button component.',
-    args: {
-      label: 'Click me',
-      size: 'md',
-      disabled: false,
-    },
-  };
+	import Button from './Button.svelte';
 </script>
 
-{#snippet Default()}
-  <Button {...args} />
-{/snippet}
+[DOCS title="Components / Button" description="A flexible button component."]
+
+	[preview component={Button} args={{ label: 'Click me', disabled: false }}]
+		<Button {...args} />
+	[/preview]
 
-{#snippet WithIcon()}
-  <Button>
-    <Icon name="settings" /> Settings
-  </Button>
-{/snippet}
+	[example title="With icon"]
+		<Button><Icon name="settings" /> Settings</Button>
+	[/example]
+
+[/DOCS]
 ```
 
-- **`component`** — the Svelte component to document (auto-extracts props, events, snippets, methods, state, CSS custom properties)
-- **`title`** — slash-separated path for sidebar navigation (e.g. `'Components / Button'`)
-- **`args`** — default prop values, used as initial values for interactive controls
-- **`Default` snippet** — gets live interactive controls. Auto-generated as `<Component {...args} />` if omitted.
-- **Named snippets** — static examples listed in the sidebar
+- **`[preview]`** — a live showcase with interactive controls.
+  `component={X}` names the previewed component (its props, events,
+  snippets, methods, state, and CSS custom properties are extracted
+  automatically) and `args` sets the control defaults. A `[DOCS]` block can
+  hold several previews — they render as tabs, each fully live.
+- **`[example]`** — frozen showcases rendered exactly as written, shown
+  below the preview area. Each needs a unique `title`.
+- **`title`** — slash-separated path for sidebar navigation.
 
-### Page Docs (`.page.sdoc`)
+### Pages — `[PAGE]`
 
-Freeform content pages with auto-generated table of contents.
+Freeform markdown content with `{expression}` interpolation and Svelte
+component islands; code fences are inert. The table of contents is generated
+from the headings.
 
-```svelte
-<!-- GettingStarted.page.sdoc -->
-<script lang="ts">
-  export const meta = {
-    title: 'Docs / Getting Started',
-    description: 'How to set up sdocs.',
-  };
-</script>
+```sdoc
+[PAGE title="Docs / Getting Started"]
 
-<h1>Getting Started</h1>
-<p>Install sdocs and create your first doc file.</p>
+	## Installation
 
-<h2>Installation</h2>
-<p>Run <code>npm install sdocs</code>...</p>
-```
+	Run `npm install sdocs` and create your first doc file.
 
-Table of contents is auto-generated from `<h2>`, `<h3>`, and `<h4>` headings.
+[/PAGE]
+```
 
-### Layout Docs (`.layout.sdoc`)
+### Layouts — `[LAYOUT]`
 
-Component compositions rendered in an isolated iframe.
+Full-page component compositions rendered on an isolated stage.
 
-```svelte
-<!-- LoginForm.layout.sdoc -->
+```sdoc
 <script lang="ts">
-  import Card from './Card.svelte';
-  import Input from './Input.svelte';
-  import Button from './Button.svelte';
-
-  export const meta = {
-    title: 'Patterns / Login Form',
-    description: 'A login form combining multiple components.',
-    settings: { padding: '24px' },
-  };
+	import Card from './Card.svelte';
+	import Input from './Input.svelte';
+	import Button from './Button.svelte';
 </script>
 
-<Card padding="24px">
-  <Input label="Email" type="email" />
-  <Input label="Password" type="password" />
-  <Button>Sign in</Button>
-</Card>
+[LAYOUT title="Patterns / Login Form" padding="24px"]
+
+	<Card padding="24px">
+		<Input label="Email" type="email" />
+		<Input label="Password" type="password" />
+		<Button>Sign in</Button>
+	</Card>
+
+[/LAYOUT]
 ```
 
+The full language reference lives at
+[gabilungu.github.io/sdocs/language](https://gabilungu.github.io/sdocs/language).
+
 ## Prop Extraction
 
 sdocs automatically extracts from your Svelte components:
@@ -200,7 +187,7 @@ JSDoc comments on props are picked up as descriptions.
 
 ## Interactive Controls
 
-The Default snippet gets live controls based on prop types:
+Each preview gets live controls based on prop types:
 
 | Prop Type | Control |
 |-----------|---------|
@@ -275,6 +262,8 @@ sidebar: {
 | `sdocs/vite` | Vite plugin function |
 | `sdocs/explorer` | Explorer.svelte UI component |
 | `sdocs/ui` | Reusable UI components (Button, Frame, Icon, Control, NavTree, Stack) |
+| `sdocs/language` | The sdoc scanner, parser, and Svelte projection |
+| `sdocs/grammar/sdoc.tmLanguage.json` | TextMate grammar for editors and highlighters |
 
 ## License
 

package/dist/grammar/sdoc.tmLanguage.json

@@ -2,15 +2,31 @@
 	"$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
 	"name": "sdoc",
 	"scopeName": "source.sdoc",
-	"fileTypes": ["sdoc"],
+	"fileTypes": [
+		"sdoc"
+	],
 	"patterns": [
-		{ "include": "#comment" },
-		{ "include": "#script-ts" },
-		{ "include": "#script-js" },
-		{ "include": "#style" },
-		{ "include": "#docs" },
-		{ "include": "#page" },
-		{ "include": "#layout" }
+		{
+			"include": "#comment"
+		},
+		{
+			"include": "#script-ts"
+		},
+		{
+			"include": "#script-js"
+		},
+		{
+			"include": "#style"
+		},
+		{
+			"include": "#docs"
+		},
+		{
+			"include": "#page"
+		},
+		{
+			"include": "#layout"
+		}
 	],
 	"repository": {
 		"comment": {
@@ -19,204 +35,415 @@
 			"end": "-->"
 		},
 		"script-ts": {
-			"begin": "^\\s*(<)(script)(?=[^>]*lang=([\"'])ts\\3)",
+			"begin": "^\\s*(<)(script)((?=[^>]*lang=([\"'])ts\\4)[^>]*)(>)",
 			"beginCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.script.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.script.sdoc"
+				},
+				"3": {
+					"patterns": [
+						{
+							"include": "#tag-attributes"
+						}
+					]
+				},
+				"5": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
 			"end": "(</)(script)\\s*(>)",
 			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.script.sdoc" },
-				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.script.sdoc"
+				},
+				"3": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
+			"contentName": "source.ts",
 			"patterns": [
-				{ "include": "#tag-rest" },
 				{
-					"begin": "(?<=>)",
-					"end": "(?=</script)",
-					"contentName": "source.ts",
-					"patterns": [{ "include": "source.ts" }]
+					"include": "source.ts"
 				}
 			]
 		},
 		"script-js": {
-			"begin": "^\\s*(<)(script)(?![^>]*lang=([\"'])ts\\3)(?=[\\s>])",
+			"begin": "^\\s*(<)(script)((?![^>]*lang=([\"'])ts\\4)[^>]*)(>)",
 			"beginCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.script.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.script.sdoc"
+				},
+				"3": {
+					"patterns": [
+						{
+							"include": "#tag-attributes"
+						}
+					]
+				},
+				"5": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
 			"end": "(</)(script)\\s*(>)",
 			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.script.sdoc" },
-				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.script.sdoc"
+				},
+				"3": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
+			"contentName": "source.js",
 			"patterns": [
-				{ "include": "#tag-rest" },
 				{
-					"begin": "(?<=>)",
-					"end": "(?=</script)",
-					"contentName": "source.js",
-					"patterns": [{ "include": "source.js" }]
+					"include": "source.js"
 				}
 			]
 		},
 		"style": {
-			"begin": "^\\s*(<)(style)(?=[\\s>])",
+			"begin": "^\\s*(<)(style)([^>]*)(>)",
 			"beginCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.style.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.style.sdoc"
+				},
+				"3": {
+					"patterns": [
+						{
+							"include": "#tag-attributes"
+						}
+					]
+				},
+				"4": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
 			"end": "(</)(style)\\s*(>)",
 			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.style.sdoc" },
-				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.style.sdoc"
+				},
+				"3": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
+			"contentName": "source.css",
 			"patterns": [
-				{ "include": "#tag-rest" },
 				{
-					"begin": "(?<=>)",
-					"end": "(?=</style)",
-					"contentName": "source.css",
-					"patterns": [{ "include": "source.css" }]
+					"include": "source.css"
 				}
 			]
 		},
-		"tag-rest": {
-			"begin": "\\G",
-			"end": "(>)",
-			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.end.sdoc" }
-			},
-			"patterns": [{ "include": "#attributes" }]
-		},
 		"docs": {
 			"name": "meta.block.docs.sdoc",
-			"begin": "^\\s*(\\[)(DOCS)\\b",
+			"begin": "^\\s*(\\[)(DOCS)\\b(.*)$",
 			"beginCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "keyword.control.entity.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "keyword.control.entity.sdoc"
+				},
+				"3": {
+					"patterns": [
+						{
+							"include": "#attributes"
+						}
+					]
+				}
 			},
 			"end": "^\\s*(\\[/)(DOCS)(\\])\\s*$",
 			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "keyword.control.entity.sdoc" },
-				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "keyword.control.entity.sdoc"
+				},
+				"3": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
 			"patterns": [
-				{ "include": "#opener-attrs" },
-				{ "include": "#comment" },
-				{ "include": "#preview" },
-				{ "include": "#example" }
+				{
+					"include": "#comment"
+				},
+				{
+					"include": "#opener-continuation"
+				},
+				{
+					"include": "#preview"
+				},
+				{
+					"include": "#example"
+				}
 			]
 		},
 		"page": {
 			"name": "meta.block.page.sdoc",
-			"begin": "^\\s*(\\[)(PAGE)\\b",
+			"begin": "^\\s*(\\[)(PAGE)\\b(.*)$",
 			"beginCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "keyword.control.entity.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "keyword.control.entity.sdoc"
+				},
+				"3": {
+					"patterns": [
+						{
+							"include": "#attributes"
+						}
+					]
+				}
 			},
 			"end": "^\\s*(\\[/)(PAGE)(\\])\\s*$",
 			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "keyword.control.entity.sdoc" },
-				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "keyword.control.entity.sdoc"
+				},
+				"3": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
 			"patterns": [
-				{ "include": "#opener-attrs" },
-				{ "include": "source.svelte" }
+				{
+					"begin": "(^|\\G)",
+					"while": "(^|\\G)(?!\\s*\\[/PAGE\\]\\s*$)",
+					"patterns": [
+						{
+							"include": "source.svelte"
+						}
+					]
+				}
 			]
 		},
 		"layout": {
 			"name": "meta.block.layout.sdoc",
-			"begin": "^\\s*(\\[)(LAYOUT)\\b",
+			"begin": "^\\s*(\\[)(LAYOUT)\\b(.*)$",
 			"beginCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "keyword.control.entity.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "keyword.control.entity.sdoc"
+				},
+				"3": {
+					"patterns": [
+						{
+							"include": "#attributes"
+						}
+					]
+				}
 			},
 			"end": "^\\s*(\\[/)(LAYOUT)(\\])\\s*$",
 			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "keyword.control.entity.sdoc" },
-				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "keyword.control.entity.sdoc"
+				},
+				"3": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
 			"patterns": [
-				{ "include": "#opener-attrs" },
-				{ "include": "source.svelte" }
+				{
+					"begin": "(^|\\G)",
+					"while": "(^|\\G)(?!\\s*\\[/LAYOUT\\]\\s*$)",
+					"patterns": [
+						{
+							"include": "source.svelte"
+						}
+					]
+				}
 			]
 		},
 		"preview": {
 			"name": "meta.block.preview.sdoc",
-			"begin": "^\\s*(\\[)(preview)\\b",
+			"begin": "^\\s*(\\[)(preview)\\b(.*)$",
 			"beginCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.sdoc"
+				},
+				"3": {
+					"patterns": [
+						{
+							"include": "#attributes"
+						}
+					]
+				}
 			},
 			"end": "^\\s*(\\[/)(preview)(\\])\\s*$",
 			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.sdoc" },
-				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.sdoc"
+				},
+				"3": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
 			"patterns": [
-				{ "include": "#opener-attrs" },
-				{ "include": "source.svelte" }
+				{
+					"begin": "(^|\\G)",
+					"while": "(^|\\G)(?!\\s*\\[/preview\\]\\s*$)",
+					"patterns": [
+						{
+							"include": "source.svelte"
+						}
+					]
+				}
 			]
 		},
 		"example": {
 			"name": "meta.block.example.sdoc",
-			"begin": "^\\s*(\\[)(example)\\b",
+			"begin": "^\\s*(\\[)(example)\\b(.*)$",
 			"beginCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.sdoc"
+				},
+				"3": {
+					"patterns": [
+						{
+							"include": "#attributes"
+						}
+					]
+				}
 			},
 			"end": "^\\s*(\\[/)(example)(\\])\\s*$",
 			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.begin.sdoc" },
-				"2": { "name": "entity.name.tag.sdoc" },
-				"3": { "name": "punctuation.definition.tag.end.sdoc" }
+				"1": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"2": {
+					"name": "entity.name.tag.sdoc"
+				},
+				"3": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
 			},
 			"patterns": [
-				{ "include": "#opener-attrs" },
-				{ "include": "source.svelte" }
+				{
+					"begin": "(^|\\G)",
+					"while": "(^|\\G)(?!\\s*\\[/example\\]\\s*$)",
+					"patterns": [
+						{
+							"include": "source.svelte"
+						}
+					]
+				}
 			]
 		},
-		"opener-attrs": {
-			"begin": "\\G",
-			"end": "(\\])",
-			"endCaptures": {
-				"1": { "name": "punctuation.definition.tag.end.sdoc" }
-			},
-			"patterns": [{ "include": "#attributes" }]
+		"opener-continuation": {
+			"comment": "Attribute lines of a multi-line opener: lines before the block body that end the opener or continue it.",
+			"match": "^\\s*((?:[A-Za-z_][\\w-]*\\s*=.*)?)(\\])\\s*$",
+			"captures": {
+				"1": {
+					"patterns": [
+						{
+							"include": "#attributes"
+						}
+					]
+				},
+				"2": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
+			}
+		},
+		"tag-attributes": {
+			"patterns": [
+				{
+					"match": "([A-Za-z_][\\w:-]*)(=)?",
+					"captures": {
+						"1": {
+							"name": "entity.other.attribute-name.sdoc"
+						},
+						"2": {
+							"name": "punctuation.separator.key-value.sdoc"
+						}
+					}
+				},
+				{
+					"name": "string.quoted.double.sdoc",
+					"begin": "\"",
+					"end": "\""
+				},
+				{
+					"name": "string.quoted.single.sdoc",
+					"begin": "'",
+					"end": "'"
+				}
+			]
 		},
 		"attributes": {
 			"patterns": [
 				{
 					"match": "([A-Za-z_][\\w-]*)\\s*(=)",
 					"captures": {
-						"1": { "name": "entity.other.attribute-name.sdoc" },
-						"2": { "name": "punctuation.separator.key-value.sdoc" }
+						"1": {
+							"name": "entity.other.attribute-name.sdoc"
+						},
+						"2": {
+							"name": "punctuation.separator.key-value.sdoc"
+						}
 					}
 				},
 				{
-					"match": "([A-Za-z_][\\w-]*)",
-					"name": "entity.other.attribute-name.sdoc"
+					"match": "\\]\\s*$",
+					"name": "punctuation.definition.tag.end.sdoc"
 				},
 				{
 					"name": "string.quoted.double.sdoc",
 					"begin": "\"",
 					"end": "\"",
 					"beginCaptures": {
-						"0": { "name": "punctuation.definition.string.begin.sdoc" }
+						"0": {
+							"name": "punctuation.definition.string.begin.sdoc"
+						}
 					},
 					"endCaptures": {
-						"0": { "name": "punctuation.definition.string.end.sdoc" }
+						"0": {
+							"name": "punctuation.definition.string.end.sdoc"
+						}
 					}
 				},
-				{ "include": "#expression" }
+				{
+					"include": "#expression"
+				},
+				{
+					"match": "([A-Za-z_][\\w-]*)",
+					"name": "entity.other.attribute-name.sdoc"
+				}
 			]
 		},
 		"expression": {
@@ -224,21 +451,35 @@
 			"begin": "\\{",
 			"end": "\\}",
 			"beginCaptures": {
-				"0": { "name": "punctuation.section.embedded.begin.sdoc" }
+				"0": {
+					"name": "punctuation.section.embedded.begin.sdoc"
+				}
 			},
 			"endCaptures": {
-				"0": { "name": "punctuation.section.embedded.end.sdoc" }
+				"0": {
+					"name": "punctuation.section.embedded.end.sdoc"
+				}
 			},
-			"patterns": [{ "include": "#expression-inner" }]
+			"patterns": [
+				{
+					"include": "#expression-inner"
+				}
+			]
 		},
 		"expression-inner": {
 			"patterns": [
 				{
 					"begin": "\\{",
 					"end": "\\}",
-					"patterns": [{ "include": "#expression-inner" }]
+					"patterns": [
+						{
+							"include": "#expression-inner"
+						}
+					]
 				},
-				{ "include": "source.ts" }
+				{
+					"include": "source.ts"
+				}
 			]
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "A lightweight documentation tool for Svelte 5 components",
   "type": "module",
   "license": "MIT",