@voithos-labs/aragonite 0.10.1 → 0.10.2

package/README.md

@@ -22,11 +22,16 @@ npm install @voithos-labs/aragonite
 	import '@voithos-labs/aragonite/styles/editor-theme.css';
 
 	let editor;
+	const source = '# Hello\n';
 </script>
 
-<Editor bind:this={editor} source={'# Hello\n'} theme="dark" />
+<div class="aragonite-editor-theme" data-editor-theme="light">
+	<Editor bind:this={editor} {source} theme="light" />
+</div>
 ```
 
+(the wrapper switches on the built-in look, and it says `light` twice because the editor paints no background of its own: the wrapper and the editor both have to match the page they land on, and a fresh app's page is white. On a dark page write `dark` in both spots, or write nothing, dark being the default.)
+
 To save the source, just do something like:
 
 ```svelte

package/dist/components/Editor.svelte

@@ -1715,7 +1715,8 @@
 		   declaration scales the whole surface. */
 		font-size: var(--editor-font-size, 1rem);
 		line-height: 1.6;
-		color: var(--color-text-primary, #ffffff);
+		/* Inherit rather than assume a dark host: an unthemed page keeps its own text color. */
+		color: var(--color-text-primary, currentColor);
 		min-height: 200px;
 		overflow-y: auto;
 		/* The editor corrects the scroll anchor by hand (list-windowing's

package/dist/editor-props.d.ts

@@ -49,7 +49,9 @@ export interface EditorProps {
     scrollMode?: 'self' | 'host';
     /** Theme name reflected to `data-editor-theme` on the editor root. Built-ins:
      *  `'dark'` (default) and `'light'`; any other value activates a consumer's
-     *  own `.editor[data-editor-theme='<name>']` token block. */
+     *  own `.editor[data-editor-theme='<name>']` token block. The editor paints no
+     *  background, so the name should match the page; an `aragonite-editor-theme`
+     *  wrapper keys its own palette off the same attribute set on the wrapper. */
     theme?: string;
     /** How the document presents, read live like `theme`; `'source'` by default. The consumer
      *  guide's Presentation modes section describes what each rung shows and allows. */

package/dist/plugins/parrot/ParrotBlock.svelte

@@ -318,7 +318,7 @@ cNd.........................................;lOc
 			color: #3fd3d3;
 		}
 		85.714% {
-			color: var(--color-text-primary, #ffffff);
+			color: var(--color-text-primary, currentColor);
 		}
 	}
 	@media (prefers-reduced-motion: reduce) {

package/docs/guide/consumer-guide.md

@@ -50,9 +50,12 @@ The editor owns the caret, the tree, and the undo stack. You own load, save, and
 	import '@voithos-labs/aragonite/styles/editor-theme.css';
 
 	let editor;
+	const source = '# Hello\n';
 </script>
 
-<Editor bind:this={editor} source={'# Hello\n'} theme="dark" />
+<div class="aragonite-editor-theme" data-editor-theme="light">
+	<Editor bind:this={editor} {source} theme="light" />
+</div>
 <button onclick={() => save(editor.getSource())}>Save</button>
 ```
 
@@ -60,7 +63,7 @@ A few things in the above example snippet are decently important; you might want
 
 1. **`source` seeds the document at mount**, and re-seeds it if the prop later changes. It's not a two way bound: the editor never writes back into it, so the document you read is always `getSource()`.
 2. **`bind:this` is how you talk to a mounted editor.** For example, you might want to use important read functions like `getSource()` and `getSelection()`, or important write functions like `setSelection()` and `runCommand()`. [The instance surface](#the-instance-surface) covers all of it.
-3. **Theming is CSS custom properties.** [Theming](#theming) has the variables and how to customize yours.
+3. **The editor paints no background of its own.** It inherits your page, so its mode has to match the page it lands on, and it says `light` twice because there are two things to match: the wrapper carries the built-in look (font, colors) for everything inside it, and the `theme` prop keys the editor's own surfaces. A fresh app's page is white, hence `light`; on a dark page write `dark` in both spots, or write nothing, dark being the default. Skip the wrapper if your app already declares the tokens; [Theming](#theming) has the two tiers and how to customize yours.
 
 Two more that aren't in the snippet but bite early: plugin registration is process-global and happens once at mount, but each editor activates exactly the plugins its own `plugins` prop lists ([Plugins](#plugins)); and `editor.__test.*` is internal and will move, so don't build on it.
 
@@ -645,7 +648,7 @@ A live change is supported, and virtual rendering re-estimates the document at t
 
 Outside this contract sits the editor's own visual language: the syntax and code-token palettes, the marker colors, the selection, search, and reorder tints (derived from `--color-selection`, above), and the surfaces windowing paints where blocks aren't mounted yet. Those are dark-based or mode-independent; read `editor-theme.css` if you mean to retheme them.
 
-**Plugin fallbacks.** A plugin reading a token keeps an inline fallback (`var(--color-text-muted, #aaaaaa)`) so it renders with no host, and every fallback matches the token's dark base value in `editor-theme.css`, never the light one. Which scopes a fallback fires in follows the tier: an editor-owned token defaults on `.editor`, so its fallback only fires outside the editor, while a host-chrome token defaults behind the opt-in class alone, so in a host that skips the class the fallback fires inside `.editor` too.
+**Plugin fallbacks.** A plugin reading a token keeps an inline fallback (`var(--color-text-muted, #aaaaaa)`) so it renders with no host, and every fallback matches the token's dark base value in `editor-theme.css`, never the light one. The one exception is the text color: it falls back to `currentColor`, so an editor with no host tokens and no wrapper inherits the page's own text instead of painting white on whatever the page is. Which scopes a fallback fires in follows the tier: an editor-owned token defaults on `.editor`, so its fallback only fires outside the editor, while a host-chrome token defaults behind the opt-in class alone, so in a host that skips the class the fallback fires inside `.editor` too.
 
 ## Keyboard shortcuts
 

package/docs/guide/plugin-guide.md

@@ -305,7 +305,7 @@ cNo.....................................oc
 			color: #3fd3d3;
 		}
 		85.714% {
-			color: var(--color-text-primary, #ffffff);
+			color: var(--color-text-primary, currentColor);
 		}
 	}
 	@media (prefers-reduced-motion: reduce) {
@@ -916,7 +916,9 @@ Pass the plugin to the editor's `plugins` prop. It installs before the seed pars
 	let editor = $state();
 </script>
 
-<Editor bind:this={editor} source={SEED} {plugins} theme="light" />
+<div class="aragonite-editor-theme" data-editor-theme="light">
+	<Editor bind:this={editor} source={SEED} {plugins} theme="light" />
+</div>
 ```
 
 The chords are live (a **chord** is a key combination, written `Mod+7` where `Mod` is Ctrl, or Cmd on a Mac). Focus the box, press `Mod+8` to debunk the theory (the string comes down and the stamp lands) and `Mod+7` to allege it again, then read `editor.getSource()` back and watch the opener line flip between the two names:
@@ -931,7 +933,7 @@ editor.getSource();
 
 The flip is one undoable edit, so undo un-debunks it, which is how conspiracies work anyway. And because the verdict lives in the bytes, a debunked conspiracy stays debunked across a reload.
 
-One thing that surprises people pasting this into a fresh app: `theme="light"` flips only the editor-owned colors, so the page still looks dark. The built-in light chrome wants the `aragonite-editor-theme` class on a wrapper element; [consumer-guide.md](consumer-guide.md)'s theming section explains the two tiers.
+The wrapper and the two `light`s are there because the editor paints no background of its own. A fresh app's page is white, so the built-in chrome (the wrapper's attribute) and the editor's own surfaces (the prop) both have to say so; on a dark page, both say `dark`, or nothing. [consumer-guide.md](consumer-guide.md)'s theming section explains the two tiers.
 
 Want a collapse toggle? Give `reservedChrome` an `isCollapsed` probe over the node, and every focus walk, merge, and windowing decision (a collapsed body stays unmounted) reads that one declaration. Add `expandPatch` beside it, returning the metadata patch that opens the node, and a reveal into the collapsed body (a table-of-contents entry, a search match) opens the container first and commits it as one undoable edit. Without it, such a reveal has nowhere to land and reports that it didn't.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@voithos-labs/aragonite",
-	"version": "0.10.1",
+	"version": "0.10.2",
 	"description": "Svelte 5 block editor for GFM Markdown with byte-for-byte lossless round-trip and a plugin platform",
 	"keywords": [
 		"markdown",