@citisen/litearea 0.1.0 → 0.2.0

package/README.md

@@ -59,15 +59,17 @@ So this library makes the opposite choices, and each one is load-bearing:
 npm install @citisen/litearea
 ```
 
-Three entry points and one stylesheet:
+Three entry points:
 
 | Import | What it is |
 | --- | --- |
 | `@citisen/litearea` | The pure engine plus the DOM layer (`createEditor`, `LiteArea`) |
 | `@citisen/litearea/react` | The React binding (`LiteAreaEditor`) |
-| `@citisen/litearea/grammars` | The two worked example grammars |
 | `@citisen/litearea/styles.css` | The same stylesheet the editor injects, for hosts that link CSS |
 
+There is no grammar entry point. The library ships no syntax at all — a caller
+supplies the rules — and nothing in `src/core/` imports a language.
+
 React is an optional peer dependency (`react >= 18`) and the only peer. The
 package has no runtime dependencies at all. The stylesheet is injected into the
 document once, on the first editor, unless `injectStyles: false` is passed.
@@ -299,25 +301,44 @@ diagnostic vocabulary, and an end-to-end walkthrough that adds `analyze`,
 `checks`, and `validate` to this same language — is in
 [docs/grammar.md](docs/grammar.md).
 
-## The two reference grammars
+## No grammar is shipped
 
-The core ships no syntax: there is no built-in language, no language identifier
-to switch on, and nothing in `src/core/` that knows what a font stack is. The two
-grammars in `@citisen/litearea/grammars` exist to check that claim rather than
-merely assert it. Both are real DSLs from the two plugins this library came out
-of, and both are importable by a host that does not want to retype a language
-that already exists:
+There is no built-in language, no language identifier to switch on, no bundled
+tokenizer, and no grammar to import: nothing in `src/core/` knows what a font
+stack is, and the package publishes no grammar entry point. A caller supplies the
+rules, and the two examples in this file are the whole of what this repository
+offers as a worked language.
 
-| Grammar | The language | What it exercises |
-| --- | --- | --- |
-| `dshSentryStyleGrammar()` | dsh-sentry's appearance document: one line per session state, then positional values or `key=value` pairs | A first-word vocabulary with rejection, an analysis that both fills slots and records the problems it found, a declarative `check`, two completion sources using `sortText`, and hover from vocabulary documentation |
-| `dshFontQueryGrammar()` | dsh-font's font query: a CSS font-family list with the weight written beside the family it belongs to | Quote handling in the lexical rules, a `scope` function that reads the analysis, dynamic vocabularies resolved from the host's installed catalogue, multi-word phrases, completion that inserts *before* an entry, and a semantic decoration |
+That is a deliberate boundary rather than an omission. The editor came out of two
+plugins with real DSLs — dsh-sentry's appearance document and dsh-font's font
+query — and each of those grammars now lives beside the plugin that owns it, as a
+grammar object the plugin hands to `createEditor` (or to `LiteAreaEditor`). The
+shape of one is worth showing, because it is what a grammar written against a real
+product looks like, and because it says plainly whose code it is:
+
+```ts
+// In the dsh-font plugin, NOT in litearea. The plugin owns the language; the
+// library owns the engine that reads it, and ships no language of its own.
+export const fontQueryGrammar = defineGrammar({
+  id: 'dsh-font-query',
+  // `-apple-system` must be ONE word, or a completion would replace half of it.
+  wordChars: /[\p{L}\p{N}_-]/u,
+  rules: [
+    { kind: 'words', words: (context) => context.state.catalogue },
+    { kind: 'match', scope: 'family.generic', pattern: /monospace|sans-serif|serif/ },
+    { kind: 'match', scope: 'weight', pattern: /thin|light|regular|medium|bold/ },
+    { kind: 'match', scope: 'separator', pattern: /,/ },
+  ],
+})
+```
 
-Neither is built in. Nothing in `src/core/` imports them, no option switches them
-on, and an editor constructed without one of them has no syntax whatsoever.
+Shipping either grammar would be a scaling trap as much as an inconsistency: every
+consumer that inlines the library would carry every language, so adding a
+JavaScript, CSS, HTML, or Rust grammar later would grow the bundle of hosts that
+use none of them. A grammar belongs where the language is parsed.
 
-Two decisions in `dshSentryStyleGrammar` are worth stating, because both were
-found by comparing the grammar against the parser it edits for:
+Two decisions in that plugin's own grammar are worth stating anyway, because both
+were found by comparing the grammar against the parser it edits for:
 
 - **It is deliberately stricter than the host parser.** `parseStyle` in the
   plugin does no value checking for a known option: it writes `shape=bogus` into
@@ -403,7 +424,7 @@ Colours, spacing, and the type scale come from custom properties on the wrapper:
 | `--litearea-accent` / `--litearea-accent-soft` / `--litearea-selection` | `#4d6bfe` and two alpha variants |
 | `--litearea-error` / `--litearea-warning` / `--litearea-info` / `--litearea-hint` | The four severity colours |
 | `--litearea-shadow` | The floating panel's shadow |
-| `--litearea-scope-*` | One colour per scope the two reference grammars use |
+| `--litearea-scope-*` | One colour per scope name in the shipped palette, so a scope a grammar invents still has a themed colour to fall back on |
 
 A dark scheme is applied automatically from `prefers-color-scheme`.
 

package/README.zh.md

@@ -32,15 +32,16 @@
 npm install @citisen/litearea
 ```
 
-三个入口加一份样式表：
+三个入口：
 
 | 导入 | 是什么 |
 | --- | --- |
 | `@citisen/litearea` | 纯引擎加上 DOM 层（`createEditor`、`LiteArea`） |
 | `@citisen/litearea/react` | React 绑定（`LiteAreaEditor`） |
-| `@citisen/litearea/grammars` | 两个作为范例的 grammar |
 | `@citisen/litearea/styles.css` | 编辑器自己注入的那份样式表，给想用 `<link>` 的宿主 |
 
+没有 grammar 入口。这个库一点语法都不带 —— 规则由调用方提供 —— `src/core/` 里也不导入任何语言。
+
 React 是可选的 peer 依赖（`react >= 18`），也是唯一的 peer 依赖。这个包没有任何运行时依赖。样式表在第一个编辑器创建时注入文档一次，除非传 `injectStyles: false`。
 
 ## 快速开始
@@ -256,18 +257,31 @@ export const formSchema = defineGrammar({
 
 完整参考 —— 每种规则的全部字段、优先级、诊断词汇，以及在同一门语言上补出 `analyze`、`checks`、`validate` 的端到端走查 —— 在 [docs/grammar.md](docs/grammar.md)。
 
-## 两个参考 grammar
+## 不带任何 grammar
 
-核心不含语法：没有内置语言、没有可以 switch 的语言标识，`src/core/` 里没有任何代码知道字体栈是什么。`@citisen/litearea/grammars` 里的两个 grammar 是为了**验证**这个说法，而不是仅仅声明它。两门语言都是真实的 DSL，来自这个库所出的那两个插件；不想重打一遍已有语言的宿主可以直接导入：
+没有内置语言、没有可以 switch 的语言标识、没有捆绑的分词器，也没有可以导入的 grammar：`src/core/` 里没有任何代码知道字体栈是什么，包里也不发布 grammar 入口。规则由调用方提供，本文里的两个例子就是这个仓库给出的全部"写好的语言"。
 
-| Grammar | 语言 | 用到了什么 |
-| --- | --- | --- |
-| `dshSentryStyleGrammar()` | dsh-sentry 的外观文档：一个会话状态一行，后面跟位置取值或 `key=value` | 行首词汇表加拒绝、一次同时填槽位并记录问题的分析、一条声明式 `check`、两个用 `sortText` 的补全来源、来自 vocabulary 文档的悬浮说明 |
-| `dshFontQueryGrammar()` | dsh-font 的字体查询：一条 CSS font-family 列表，字重写在它所属的字族旁边 | 词法规则里处理引号、读分析结果的 `scope` 函数、从宿主已安装目录解析出来的动态 vocabulary、多词短语、**插到前面**的补全、以及一个语义 decoration |
+这是一条刻意划下的边界，而不是遗漏。这个编辑器出自两个带真实 DSL 的插件 —— dsh-sentry 的外观文档和 dsh-font 的字体查询 —— 而这两个 grammar 现在都待在拥有它们的插件身边，作为插件交给 `createEditor`（或 `LiteAreaEditor`）的 grammar 对象。其中一个的样子值得看一眼，因为它展示了"针对真实产品写的 grammar"长什么样，也因为它清楚地说明了这段代码归谁：
+
+```ts
+// 在 dsh-font 插件里，不在 litearea 里。语言归插件所有；库只拥有读它的引擎，
+// 自己一点语言都不带。
+export const fontQueryGrammar = defineGrammar({
+  id: 'dsh-font-query',
+  // `-apple-system` 必须算作一个词，否则补全会只替换它的一半。
+  wordChars: /[\p{L}\p{N}_-]/u,
+  rules: [
+    { kind: 'words', words: (context) => context.state.catalogue },
+    { kind: 'match', scope: 'family.generic', pattern: /monospace|sans-serif|serif/ },
+    { kind: 'match', scope: 'weight', pattern: /thin|light|regular|medium|bold/ },
+    { kind: 'match', scope: 'separator', pattern: /,/ },
+  ],
+})
+```
 
-两个都不是内置的。`src/core/` 不导入它们，没有任何选项能打开它们，不带 grammar 构造出来的编辑器一点语法都没有。
+把其中任何一个 grammar 打进包里，既是扩展性陷阱，也是前后不一致：每个内联了这个库的消费者都会背上所有语言，以后再想加 JavaScript、CSS、HTML 或 Rust 的 grammar，就会让完全用不到它们的宿主包体变大。语言应该待在解析它的地方。
 
-`dshSentryStyleGrammar` 里有两个决定值得单独说明，因为它们都是拿 grammar 和被编辑的解析器对照之后发现的：
+不过，那个插件自己的 grammar 里有两个决定仍然值得单独说明，因为它们都是拿 grammar 和被编辑的解析器对照之后发现的：
 
 - **它刻意比宿主解析器更严格。** 插件里的 `parseStyle` 对已知选项不做取值检查：它把 `shape=bogus` 原样写进规则，之后由 `resolveLook` 悄悄换成出厂默认值，于是拼错的表现只是"图标怎么都不变"。这个 grammar 会把它报出来 —— 报成 warning 而不是 error，因为文档仍然能用，只是它说的不是它想说的。
 - **它不接受 `fallback` 作为一个状态。** 插件自己的模块注释里写着 `fallback none`，但 `STYLE_STATES` 只有那四个状态，`fallback` 是内部从 `STYLE_FALLBACK_LOOK` 推导出来的，从来就没有被解析过。那句注释是过期的，把它照抄进 grammar，只会让编辑器和它服务的解析器互相矛盾。
@@ -327,7 +341,7 @@ export const formSchema = defineGrammar({
 | `--litearea-accent` / `--litearea-accent-soft` / `--litearea-selection` | `#4d6bfe` 以及两个带透明度的变体 |
 | `--litearea-error` / `--litearea-warning` / `--litearea-info` / `--litearea-hint` | 四种严重级别的颜色 |
 | `--litearea-shadow` | 浮层的阴影 |
-| `--litearea-scope-*` | 两个参考 grammar 用到的每个 scope 的颜色 |
+| `--litearea-scope-*` | 出厂调色板里每个 scope 名字一个颜色，所以 grammar 自己新造的 scope 也有主题色可回退 |
 
 深色方案由 `prefers-color-scheme` 自动应用。
 

package/dist/types/core/types.d.ts

@@ -36,9 +36,9 @@ export interface Token extends Range {
  * tokens and they are deliberately not tokens here.
  *
  * The distinction earns its keep. A token is what the *characters* are; a
- * decoration is what they *mean*, and the two change on different schedules. The
- * font-query grammar paints `Geist Mono` as a family from the characters alone,
- * but which family is *in effect* depends on the installed catalogue — the same
+ * decoration is what they *mean*, and the two change on different schedules. A
+ * grammar can paint `Geist Mono` as a family from the characters alone, but which
+ * family is *in effect* depends on a catalogue the HOST supplied — the same
  * characters mean something else on another machine. Painting that as a token
  * would mean re-lexing the document whenever the catalogue changed; painting it
  * as a decoration means recomputing one range list, which is what it is.
@@ -431,8 +431,8 @@ export interface CompletionContext<State = unknown> {
      * `runn|` is no longer "at the start of the line" in the strict sense, but it is
      * unmistakably completing the first word. A source that asked `firstOnLine` would
      * switch itself off after the very first keystroke — which is exactly the bug this
-     * field was added to fix, and exactly the kind of thing a reference grammar is
-     * for finding.
+     * field was added to fix, and exactly the kind of thing a grammar written against
+     * a real document is for finding.
      */
     firstWord: boolean;
     /** The first non-whitespace token on the caret's line, when there is one. */

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAeA,YAAY,EACV,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,UAAU,EACV,OAAO,EACP,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,SAAS,EACT,KAAK,EACL,UAAU,EACV,kBAAkB,EAClB,IAAI,EACJ,WAAW,EACX,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,EACR,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,SAAS,EACT,WAAW,GACZ,MAAM,iBAAiB,CAAA;AAExB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEpE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAEpE,OAAO,EACL,KAAK,EACL,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,MAAM,EACN,WAAW,EACX,UAAU,EACV,OAAO,EACP,UAAU,EACV,OAAO,EACP,WAAW,EACX,YAAY,EACZ,UAAU,GACX,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,IAAI,EACJ,KAAK,eAAe,EACpB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAElF,OAAO,EACL,aAAa,EACb,cAAc,GACf,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,IAAI,EACJ,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,eAAe,EACf,QAAQ,EACR,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE/D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEnE,OAAO,EACL,eAAe,EACf,eAAe,EACf,YAAY,EACZ,UAAU,EACV,aAAa,GACd,MAAM,aAAa,CAAA;AAEpB,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAgBA,YAAY,EACV,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,UAAU,EACV,OAAO,EACP,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,SAAS,EACT,KAAK,EACL,UAAU,EACV,kBAAkB,EAClB,IAAI,EACJ,WAAW,EACX,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,EACR,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,SAAS,EACT,WAAW,GACZ,MAAM,iBAAiB,CAAA;AAExB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEpE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAEpE,OAAO,EACL,KAAK,EACL,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,MAAM,EACN,WAAW,EACX,UAAU,EACV,OAAO,EACP,UAAU,EACV,OAAO,EACP,WAAW,EACX,YAAY,EACZ,UAAU,GACX,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,IAAI,EACJ,KAAK,eAAe,EACpB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAElF,OAAO,EACL,aAAa,EACb,cAAc,GACf,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,IAAI,EACJ,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,eAAe,EACf,QAAQ,EACR,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE/D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEnE,OAAO,EACL,eAAe,EACf,eAAe,EACf,YAAY,EACZ,UAAU,EACV,aAAa,GACd,MAAM,aAAa,CAAA;AAEpB,cAAc,gBAAgB,CAAA"}

package/docs/architecture.md

@@ -265,11 +265,15 @@ of them are exactly why `scripts/browser-check.mjs` exists: a textarea's undo
 stack has no API to read and no way to fake, so the only honest test is to make an
 edit and undo it in a browser that has a real one.
 
-The harness bundles the **shipped** `dist/` files rather than `src/` — so what it
-drives is the artifact a host installs — inlines them as an IIFE (Chromium refuses
-to fetch an ES module from a `file://` URL), and drives the public API and the
-public DOM only: it mounts editors, types through `execCommand('insertText')`,
-presses keys, dispatches a `mousedown` on a row, and hovers a squiggle. The page
+The harness bundles the **shipped** `dist/index.js` — the package's one JavaScript
+entry point — rather than `src/`, so what it drives is the artifact a host
+installs, and it inlines it as an IIFE (Chromium refuses to fetch an ES module
+from a `file://` URL). The language the checks run against is defined inside the
+checklist itself, because the package ships none: proving that a particular
+product DSL works in a browser belongs beside the plugin that owns it, while the
+questions here are all about the engine. It drives the public API and the public
+DOM only: it mounts editors, types through `execCommand('insertText')`, presses
+keys, dispatches a `mousedown` on a row, and hovers a squiggle. The page
 reports through `document.title`, with `error` and `unhandledrejection` listeners
 that write to the same channel, because a page whose only output channel is its
 title has to report its own failures through that channel — otherwise a syntax
@@ -311,6 +315,6 @@ again", which is all most hosts need.
 | `contenteditable` | It makes the document a DOM tree that the browser edits in ways you do not control — nested elements, `<br>` for a blank line, pasted HTML — so the value would have to be re-serialised on every keystroke, which is the same re-render problem with more failure modes and no native undo semantics worth having |
 | A second highlighting layer per range list (one for scopes, one for decorations, one for squiggles) | Each layer would have to position its own spans, so each would need its own idea of where a range starts, and a span positioned by measuring drifts as soon as the font, the wrapping, or the padding is even slightly different from what was measured. One merged stream cannot drift because nothing is positioned |
 | Measuring the live field (`scrollHeight` after collapsing it) | It reflows the page and flickers on every keystroke — the measurement that is supposed to decide the height is what makes the height unstable. The offscreen mirror pays one extra layout and keeps the field's geometry out of the question |
-| A bundled grammar (a default language, or a language registry) | The claim of the library is that the core knows no syntax. A default grammar would make that claim false, and it would be the thing every host inherited. The two reference grammars are importable and deliberately outside `src/core/` |
+| A bundled grammar (a default language, or a language registry) | The claim of the library is that the core knows no syntax. A default grammar would make that claim false, and it would be the thing every host inherited. The package therefore ships no grammar at all: a DSL lives beside the plugin that owns it and is handed to the editor as a value |
 | Synthetic `beforeinput`/`InputEvent` edits | Untrusted, so the browser will not run them through the editing pipeline: the text changes and the history does not, which is worse than a documented `'direct'` fallback because it fails silently |
 | Tracking the caret as a character index in one module and a screen position in another | Every position that crosses a module boundary is a character offset; pixels enter only in `src/dom/`, only to place a floating element, and never travel back inward. Two coordinate systems for one caret is what produced the range that "had already moved" |

package/docs/completion.md

@@ -163,9 +163,9 @@ eligible while that head is being spelled out. `runn\|` is no longer "at the sta
 of the line" in the strict sense — the line already has content — but it is
 unmistakably completing the first word. A source that asked `firstOnLine` would
 switch itself off after the very first keystroke, which is the bug the second field
-exists to prevent. `dshSentryStyleGrammar` asks `firstWord` for exactly this
-reason, and it is the difference between a list that helps and a list that keeps
-disappearing.
+exists to prevent. A line-oriented grammar's first-word completion asks
+`firstWord` for exactly this reason, and it is the difference between a list that
+helps and a list that keeps disappearing.
 
 ## Ranking
 

package/docs/grammar.md

@@ -76,9 +76,9 @@ A function is handed everything a lexical decision could need:
 | `state` | Whatever `analyze` returned |
 
 The `state` field is the one that earns the function form: it is how a scope can
-depend on something the characters do not say. `dshFontQueryGrammar` uses it to
-paint a weight word as `weight` or `weight.missing`, which depends on the
-machine's installed faces, not on the word.
+depend on something the characters do not say. A grammar for a host's installed
+fonts uses it to paint a weight word as `weight` or `weight.missing`, which
+depends on the faces the host reported, not on the word.
 
 ### `match`: a regular expression
 
@@ -116,7 +116,7 @@ states the host actually has — costs one call, not one per token.
 
 | Field | Default | Notes |
 | --- | --- | --- |
-| `max` | 4 | The most words one entry may span. A span longer than `max` is never attempted, and four covers every family in the shipped catalogue (`Source Han Serif SC` is four) |
+| `max` | 4 | The most words one entry may span. A span longer than `max` is never attempted, and four covers a name like `Source Han Serif SC`, which is four words |
 
 The engine tries the longest span first and keeps the longest member it finds, so
 a catalogue holding both `IBM Plex` and `IBM Plex Mono` resolves the longer name.
@@ -346,10 +346,10 @@ decides three things at once:
 3. **Where a double click puts the selection**, because that is the platform's
    own word test and the browser uses the same notion of a word the field does.
 
-A language whose names contain a dot or a hyphen must say so. `dshFontQueryGrammar`
-uses `/[\p{L}\p{N}_-]/u` so `-apple-system` is one word; `dshSentryStyleGrammar`
-deliberately does *not* include `.`, so a stray `circle.` is not read as one
-unknown word and reported as a name the user never typed.
+A language whose names contain a dot or a hyphen must say so. A font query uses
+`/[\p{L}\p{N}_-]/u` so `-apple-system` is one word; a grammar whose names never
+contain a dot leaves it out, so a stray `circle.` is not read as one unknown word
+and reported as a name the user never typed.
 
 The flags are normalised: `g` and `y` are stripped from the predicate, because
 `RegExp.prototype.test` advances `lastIndex` on a global pattern and a predicate
@@ -442,7 +442,8 @@ diagnostic's `source` is always the grammar's `id`.
 
 `report` is also the place a structural walk that ran in `analyze` publishes what
 it found — record the ranges while the structure is known, and report them here.
-Both reference grammars do exactly that.
+That is the usual arrangement: `analyze` decides what is wrong and `validate`
+hands the ranges over.
 
 ### Codes and severities
 
@@ -476,12 +477,12 @@ detail and the body. Decorations are clamped into the document, dropped when the
 come out empty, and sorted — a grammar computing them from a stale parse cannot
 paint a span nobody can see.
 
-The font grammar's "in effect" pill is the worked case. `Geist Mono` is painted as
-a family from the characters alone — that is a token. Which family is *in effect*
-depends on the machine's installed catalogue, so the same characters mean
-something else on another computer. Painting that as a token would mean re-lexing
-the document whenever the catalogue changed; as a decoration it is one recomputed
-range list, which is what it actually is.
+A host's "in effect" mark is the worked case. `Geist Mono` is painted as a family
+from the characters alone — that is a token. Which family is *in effect* depends
+on the host's installed catalogue, so the same characters mean something else on
+another computer. Painting that as a token would mean re-lexing the document
+whenever the catalogue changed; as a decoration it is one recomputed range list,
+which is what it actually is.
 
 Reach for `decorate` when the mark depends on something outside the document. If
 nothing in your language does, do not add one — a decoration that could have been

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@citisen/litearea",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A lightweight textarea-based code editor: native undo/redo, fully custom syntax highlighting, VSCode-style completion, diagnostics, and hover tooltips. No CodeMirror, no Monaco.",
   "type": "module",
   "license": "MIT",
@@ -27,11 +27,6 @@
       "import": "./dist/react.js",
       "require": "./dist/react.cjs"
     },
-    "./grammars": {
-      "types": "./dist/types/grammars/index.d.ts",
-      "import": "./dist/grammars.js",
-      "require": "./dist/grammars.cjs"
-    },
     "./styles.css": "./dist/styles.css",
     "./package.json": "./package.json"
   },