@allons-y/webc-code-sample 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,385 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+1. License Grants and Conditions
+
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+1. Responsibilities
+
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+1. Inability to Comply Due to Statute or Regulation
+
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+1. Termination
+
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+
+*                                                                      *
+* 1. Disclaimer of Warranty                                           *
+* -------------------------                                           *
+*                                                                      *
+* Covered Software is provided under this License on an "as is"       *
+* basis, without warranty of any kind, either expressed, implied, or  *
+* statutory, including, without limitation, warranties that the       *
+* Covered Software is free of defects, merchantable, fit for a        *
+* particular purpose or non-infringing. The entire risk as to the     *
+* quality and performance of the Covered Software is with You.        *
+* Should any Covered Software prove defective in any respect, You     *
+* (not any Contributor) assume the cost of any necessary servicing,   *
+* repair, or correction. This disclaimer of warranty constitutes an   *
+* essential part of this License. No use of any Covered Software is   *
+* authorized under this License except under this disclaimer.         *
+*                                                                      *
+
+************************************************************************
+
+************************************************************************
+
+*                                                                      *
+* 1. Limitation of Liability                                          *
+* --------------------------                                          *
+*                                                                      *
+* Under no circumstances and under no legal theory, whether tort      *
+* (including negligence), contract, or otherwise, shall any           *
+* Contributor, or anyone who distributes Covered Software as          *
+* permitted above, be liable to You for any direct, indirect,         *
+* special, incidental, or consequential damages of any character      *
+* including, without limitation, damages for lost profits, loss of    *
+* goodwill, work stoppage, computer failure or malfunction, or any    *
+* and all other commercial damages or losses, even if such party      *
+* shall have been informed of the possibility of such damages. This   *
+* limitation of liability shall not apply to liability for death or   *
+* personal injury resulting from such party's negligence to the       *
+* extent applicable law prohibits such limitation. Some               *
+* jurisdictions do not allow the exclusion or limitation of           *
+* incidental or consequential damages, so this exclusion and          *
+* limitation may not apply to You.                                    *
+*                                                                      *
+
+************************************************************************
+
+1. Litigation
+
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+1. Miscellaneous
+
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+1. Versions of the License
+
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at <http://mozilla.org/MPL/2.0/>.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @allons-y/webc-code-sample
 
-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.
+Part of [Norn](https://github.com/allonsy-studio/webc-resources#readme). `norn-code-block` WebC component with build-time syntax highlighting. Shiki runs at build; the browser receives token ranges for the CSS Custom Highlight API and a copy button, with no highlighter shipped.
+
+See it in the [component preview](https://allonsy-studio.github.io/webc-resources/).
+
+## Status
+
+Beta. Versions are `0.1.0-beta.N` until 1.0.
+
+## Install
+
+```sh
+npm install --save-dev @11ty/eleventy @11ty/eleventy-plugin-webc @allons-y/webc-patterns @allons-y/webc-code-sample
+```
+
+Node 22 or later. Evergreen browsers from about 2024. Features newer than that, such as the CSS Custom Highlight API, degrade gracefully: the code stays readable plain text.
+
+The package registers nothing itself. It is an optional peer dependency of `@allons-y/webc-patterns`: with it installed, the Norn plugin registers `norn-code-block`, the `nornTokenRanges` helper, and the Markdown add-on, and the Norn layouts show their samples with it. The copy button is the patterns package's `norn-copy-button`.
+
+## Usage
+
+Install it beside the patterns package and add the Norn plugin (or a theme that adds it, such as `@allons-y/webc-oss-site`). There is nothing else to register:
+
+```js
+import norn from "@allons-y/webc-patterns/plugin";
+
+export default function (config) {
+	config.addPlugin(norn, { props: (data) => ({ title: data.title, name: "My project" }) });
+
+	return { markdownTemplateEngine: false };
+}
+```
+
+Without the Norn plugin, add `codeBlock` to the project's own WebC `components` list beside `patterns()` from `@allons-y/webc-patterns`, and register `tokenRanges` as `nornTokenRanges`. Without `patterns()` in the list, `norn-copy-button` is an unknown tag and the code blocks render with no copy button and no error.
+
+Call the component from a WebC page. Props take the `@` prefix:
+
+```html
+<norn-code-block @language="js" @caption="example.js" @code="const answer = 42;"></norn-code-block>
+```
+
+### Markdown
+
+The Norn plugin adds the Markdown add-on for fenced code. Without the plugin, amend the library yourself:
+
+```js
+import { highlightFences } from "@allons-y/webc-code-sample/markdown";
+
+config.amendLibrary("md", highlightFences);
+```
+
+Each fence renders as the `<norn-code-block>` an author would write, with the fence's first word as `@language`. The add-on fills no slots, so the labels and button texts come from the component's fallbacks, as in Translating below. The fence's tag is compiled by WebC, so the page's layout renders the Markdown content with `@html="content"`. Every Norn layout does, and `norn-base` does for a Markdown page that uses it directly.
+
+### Translating
+
+Every string a visitor sees or hears is content in the page, in a named slot, hidden until the script uses it: slot `label` names the code when there is no caption, `copy-label` names the copy button (`{name}` stands in for the code's name, filled in by the script), and `copy`, `copied`, and `failed` are the button's texts:
+
+```html
+<norn-code-block @language="sh" @code="npm install">
+	<span slot="label">Commande d'installation</span>
+	<span slot="copy-label">Copier la {name}</span>
+	<span slot="copy">Copier</span>
+</norn-code-block>
+```
+
+An empty slot falls back to the site's strings from the patterns package's `componentStrings`, under `norn-code-block` (`label`, with `{language}` for the language, and `copy-label`) and `norn-copy-button` (`copy`, `copied`, `failed`), then to English. That covers Markdown fences too: `highlightFences` writes no slots of its own.
+
+### Layout requirements
+
+The Norn layouts meet these. A layout of the project's own:
+
+- Links the page's bundles from the layout head, with `webc:keep` on both tags. WebC removes `<link>` and `<script src>` without it. `norn-head` does this.
+
+  ```html
+  <link rel="stylesheet" :href="getBundleFileUrl('css')" webc:keep />
+  <script :src="getBundleFileUrl('js')" defer webc:keep></script>
+  ```
+
+- Sets `markdownTemplateEngine: false`, or the default Liquid pass rewrites `{{ }}` inside fences.
+- Drops the `href=""` and `src=""` tags a page with no bundles is left with: `webc:if` can't guard them, because the URL resolves after render. The Norn plugin registers `dropEmptyBundleTags` from the patterns package as a transform for this.
+
+### Without JavaScript
+
+The code stays readable plain text, and is not a tab stop: the script makes it a named, focusable region only while it scrolls sideways. The highlight colors need the CSS Custom Highlight API and a script. The copy button is an icon over the top end corner of the code, which names itself when the pointer or focus is on it, and needs a script and the Clipboard API, which browsers expose only on secure origins (HTTPS or localhost): elsewhere it stays hidden. The code always reads left to right, in a right-to-left page too. The script registers `norn-code-block` as a custom element, so a sample added to the page later is enhanced too.
+
+### Customizing
+
+`@chrome="terminal"` frames the code with a header bar for the caption:
+
+```html
+<norn-code-block @chrome="terminal" @language="sh" @caption="Terminal" @code="npm install"></norn-code-block>
+```
+
+The sample reads shared tokens only, each falling back to its default compiled into the component, so it keeps its look with no stylesheet beside it. Set them in a project `tokens.css`:
+
+| Token | Controls |
+| --- | --- |
+| `--norn-surface-code`, `--norn-text-base` | Surface and text colors |
+| `--norn-ui-border-radius`, `--norn-space-m` | Corner radius and inner spacing |
+| `--norn-font-mono` | Font stack |
+| `--norn-code-comment`, `--norn-code-string`, `--norn-code-keyword`, `--norn-code-function`, `--norn-code-number`, `--norn-code-flag` | Syntax colors |
+
+## Exports
+
+| Export | Purpose |
+| --- | --- |
+| `codeBlock` | Absolute path to `components/norn-code-block.webc` |
+| `tokenRanges(code, language)` | Shiki tokens as the compact JSON that `data-tokens` carries, or undefined with no tokens: `[groups, numbers]`, the group names once each, then three whole numbers per range, the group's index in `groups`, the gap from the end of the range before (from 0 for the first), and the length: `[["keyword","string"],[0,0,5,1,3,4]]` is `keyword` from 0 to 5 and `string` from 8 to 12. The ranges are character offsets in order, and none overlaps the next. The groups are `comment`, `string`, `keyword`, `function`, `number`, `flag`, and `punctuation`. For `sh`, `bash`, `shell`, and `shell-session`, the command is a `function`, its subcommand a `keyword`, a flag a `flag`, and an argument a `string`. The plugin registers it as `nornTokenRanges` |
+| `decodeRanges(value)` | Reads a `tokenRanges` string back into `[group, start, end][]` character offsets. Undefined reads as `[]`; any other value that is not the compact form throws a `TypeError` that says what is wrong |
+| `loadLanguages(...languages)` | Adds Shiki language registrations beyond the defaults (`bash`, `css`, `diff`, `html`, `javascript`, `json`, `markdown`, `typescript`, `yaml`), such as `import rust from "@shikijs/langs/rust"`. Call it once, before the build highlights code |
+
+`@allons-y/webc-code-sample/markdown` exports `highlightFences(md)`, a markdown-it amend that renders fenced code as `<norn-code-block>`.
+
+## License
+
+[MPL-2.0](LICENSE): use freely, modify as needed; changes to MPL-licensed files should be shared back under the same license.
+
+<p align="center">
+<a href="https://allons-y.studio">
+    <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/allonsy-studio/.github/main/assets/png/oss-footer-dark.png">
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/allonsy-studio/.github/main/assets/png/oss-footer-light.png">
+        <img id="user-content-logo" src="https://raw.githubusercontent.com/allonsy-studio/.github/main/assets/png/oss-footer-light.png" alt="Brought to you by Allons-y Studio" width="400">
+    </picture>
+</a>
+</p>

package/components/norn-code-block.webc

@@ -0,0 +1,306 @@
+<!---
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+--->
+<script webc:setup>
+/** The code as it should paste: a leading `$ ` prompt comes off each line, and `$HOME` is untouched. */
+const pasteable = (code) =>
+	String(code)
+		.split("\n")
+		.map((line) => line.replace(/^\$\s+/, ""))
+		.join("\n");
+
+/** The code's default name: the label template with the language in it. */
+const nameOf = (language, label) =>
+	(typeof label === "string" && label ? label : "{language} code")
+		.replaceAll("{language}", typeof language === "string" ? language : "")
+		.replace(/\s+/g, " ")
+		.trim();
+</script>
+<figure :data-chrome="chrome === 'terminal' ? 'terminal' : undefined">
+	<figcaption webc:if="caption" @text="caption"></figcaption>
+	<norn-copy-button :@value="pasteable(code)" :@strings="'norn-code-block-' + uid" :@compact="true" @surface="code"></norn-copy-button>
+	<pre dir="ltr" :data-language="typeof language === 'string' && language ? language : undefined"><code :data-tokens="nornTokenRanges(code, language)" @text="code"></code></pre>
+	<span hidden :id="'norn-code-block-' + uid">
+		<span data-string="label" :id="'norn-code-block-' + uid + '-copy'"><slot name="copy-label"><span webc:nokeep @text="nornComponentStrings?.('norn-code-block', 'copy-label', $data.page) || 'Copy {name} to clipboard'"></span></slot></span>
+		<span data-string="copy"><slot name="copy"><span webc:nokeep @text="nornComponentStrings?.('norn-copy-button', 'copy', $data.page) || 'Copy'"></span></slot></span>
+		<span data-string="copied"><slot name="copied"><span webc:nokeep @text="nornComponentStrings?.('norn-copy-button', 'copied', $data.page) || 'Copied'"></span></slot></span>
+		<span data-string="failed"><slot name="failed"><span webc:nokeep @text="nornComponentStrings?.('norn-copy-button', 'failed', $data.page) || 'Copy failed'"></span></slot></span>
+	</span>
+	<span data-name hidden><slot name="label"><span data-default @text="nameOf(language, nornComponentStrings?.('norn-code-block', 'label', $data.page))"></span></slot></span>
+</figure>
+<style>
+	@layer norn.components {
+		norn-code-block {
+			display: block;
+
+			/* The caption sits above the code. The copy button shares the code's cell, over its top end corner. */
+			& figure {
+				display: grid;
+				grid-template-columns: minmax(0, 1fr);
+				margin: 0;
+			}
+
+			& figure:has(> figcaption) {
+				row-gap: var(--norn-space-xs, 0.5rem);
+			}
+
+			& figcaption {
+				grid-area: 1 / 1;
+				color: var(--norn-text-muted, light-dark(#4b5160, #a4abba));
+				font-family: var(--norn-font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+				font-size: var(--norn-font-size-s, 0.875rem);
+			}
+
+			& norn-copy-button {
+				grid-area: 2 / 1;
+				z-index: 1;
+				justify-self: end;
+				align-self: start;
+				margin: var(--norn-space-2xs, 0.25rem);
+			}
+
+			& pre {
+				box-sizing: border-box;
+				grid-area: 2 / 1;
+				margin: 0;
+				overflow-x: auto;
+				padding: var(--norn-space-m, 1.25rem);
+				border-radius: var(--norn-ui-border-radius, 6px);
+				background: var(--norn-surface-code, light-dark(hsl(40, 14%, 94%), #2c313b));
+				color: var(--norn-text-base, light-dark(#16181d, #eceef3));
+				font-family: var(--norn-font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+				font-size: var(--norn-font-size-s, 0.875rem);
+				line-height: 1.5;
+			}
+
+			/* With the copy button showing, the code's scrolling area stops short of it. A transparent border is outside the scrolling area and under the background, so no code runs beneath the button. The button sits at the figure's end, and the code is always left to right, so a right-to-left page takes the border on the other side. */
+			& figure:has(> norn-copy-button > button:not([hidden])) {
+				--_chip: calc(2 * var(--norn-space-xs, 0.5rem) + var(--norn-ui-icon-s, 1em) + var(--norn-space-2xs, 0.25rem) + var(--norn-space-xs, 0.5rem));
+			}
+
+			& figure:has(> norn-copy-button > button:not([hidden])) > pre {
+				border-inline-end: var(--_chip) solid transparent;
+			}
+
+			& figure:dir(rtl):has(> norn-copy-button > button:not([hidden])) > pre {
+				border-inline-end: 0;
+				border-inline-start: var(--_chip) solid transparent;
+			}
+
+			& code {
+				padding: 0;
+				background: none;
+				font: inherit;
+			}
+
+			/* A frame with a header bar for the caption, for `@chrome="terminal"`. `:where()` keeps each rule as specific as the plain one it follows, so a container's rules still win. */
+			& figure:where([data-chrome="terminal"]),
+			& figure:where([data-chrome="terminal"]):has(> figcaption) {
+				overflow: hidden;
+				row-gap: 0;
+				border-radius: var(--norn-ui-border-radius, 6px);
+			}
+
+			& figure:where([data-chrome="terminal"]) > figcaption {
+				box-sizing: border-box;
+				display: flex;
+				align-items: center;
+				block-size: 2rem;
+				padding-inline: var(--norn-space-s, 0.75rem);
+				background: var(--norn-surface-raised, light-dark(hsl(40, 14%, 96%), #242932));
+			}
+
+			& figure:where([data-chrome="terminal"]) > pre {
+				border-radius: 0;
+			}
+
+			/* Colors for the ranges the script registers, set on `code` as Firefox ignores them on an ancestor. Plain text without Custom Highlight API support. */
+			& code::highlight(tok-comment) {
+				color: var(--norn-code-comment, light-dark(#566070, #9aa3b5));
+			}
+
+			& code::highlight(tok-string) {
+				color: var(--norn-code-string, light-dark(#0b6b3a, #7ed6a1));
+			}
+
+			& code::highlight(tok-keyword) {
+				color: var(--norn-code-keyword, light-dark(#6b2fc2, #c4a3ff));
+			}
+
+			& code::highlight(tok-function) {
+				color: var(--norn-code-function, light-dark(#1b4fc4, #8fb0ff));
+			}
+
+			& code::highlight(tok-number) {
+				color: var(--norn-code-number, light-dark(#9a4a00, #ffb36b));
+			}
+
+			& code::highlight(tok-flag) {
+				color: var(--norn-code-flag, light-dark(#00687a, #5ccfe0));
+			}
+
+			& code::highlight(tok-punctuation) {
+				color: var(--norn-text-muted, light-dark(#4b5160, #a4abba));
+			}
+
+			@media print {
+				break-inside: avoid;
+
+				& pre {
+					white-space: pre-wrap;
+				}
+			}
+		}
+	}
+</style>
+<script>
+	{
+		/** The ranges of every connected sample, by sample. The Custom Highlight API registry is shared by the page. */
+		const rangesBySample = new Map();
+		const supported = typeof CSS !== "undefined" && "highlights" in CSS;
+
+		/**
+		 * Read `data-tokens`: `[groups, numbers]`, the group names, then a group index, the gap from the previous range's end, and a length per range.
+		 *
+		 * @param {string} tokens
+		 * @returns {[string, number, number][]}
+		 */
+		const decode = (tokens) => {
+			const [groups, numbers] = JSON.parse(tokens);
+			const ranges = [];
+			let end = 0;
+			for (let at = 0; at < numbers.length; at += 3) {
+				const group = groups[numbers[at]];
+				const start = end + numbers[at + 1];
+				end = start + numbers[at + 2];
+				if (typeof group !== "string" || !Number.isInteger(start) || !(end > start)) throw new TypeError("Unusable data-tokens");
+				ranges.push([group, start, end]);
+			}
+			return ranges;
+		};
+
+		/** Add a sample's ranges to the page's highlights, one group at a time, so each connect costs only its own ranges. */
+		const paint = (sample, found) => {
+			rangesBySample.set(sample, found);
+			if (!supported) return;
+			for (const [group, range] of found) {
+				const name = `tok-${group}`;
+				if (!CSS.highlights.has(name)) CSS.highlights.set(name, new Highlight());
+				CSS.highlights.get(name).add(range);
+			}
+		};
+
+		/** Take a sample's ranges back out, and drop a group left empty. */
+		const unpaint = (sample) => {
+			const found = rangesBySample.get(sample);
+			rangesBySample.delete(sample);
+			if (!found || !supported) return;
+			for (const [group, range] of found) {
+				const name = `tok-${group}`;
+				const highlight = CSS.highlights.get(name);
+				highlight?.delete(range);
+				if (highlight?.size === 0) CSS.highlights.delete(name);
+			}
+		};
+
+		/**
+		 * Code sample enhancements. The server-rendered figure, caption, and code are the whole component without a script:
+		 * this adds the highlight colors, the copy button's name, and a tab stop only while the code scrolls.
+		 */
+		class CodeBlock extends HTMLElement {
+			#observer;
+
+			connectedCallback() {
+				if (document.readyState === "loading") {
+					document.addEventListener("DOMContentLoaded", () => this.isConnected && this.#enhance(), { once: true });
+					return;
+				}
+				this.#enhance();
+			}
+
+			disconnectedCallback() {
+				unpaint(this);
+				this.#observer?.disconnect();
+				this.#observer = undefined;
+			}
+
+			/** Safe to run again: a move reconnects the element. */
+			#enhance() {
+				const pre = this.querySelector("pre");
+				if (!pre) return;
+				const name = this.#name();
+				this.#nameCopyButton(name);
+				this.#highlight(pre.querySelector("code[data-tokens]"));
+				this.#watchOverflow(pre, name);
+			}
+
+			/** What names the code: its caption, else the `label` text. Either gets an id from the texts' holder, for `aria-labelledby`. */
+			#name() {
+				const holder = this.querySelector(":scope > figure > span[hidden][id]");
+				const named = this.querySelector(":scope > figure > figcaption") ?? this.querySelector(":scope > figure > [data-name]");
+				if (named && holder) named.id ||= `${holder.id}-name`;
+				return named;
+			}
+
+			/** Put the code's name in the copy button's, where it has `{name}`. Once filled, it has none left. */
+			#nameCopyButton(name) {
+				const label = this.querySelector(':scope > figure > [hidden] > [data-string="label"]');
+				if (!label || !name) return;
+				const walker = document.createTreeWalker(label, NodeFilter.SHOW_TEXT);
+				const words = name.textContent.trim();
+				while (walker.nextNode()) walker.currentNode.data = walker.currentNode.data.replaceAll("{name}", words);
+			}
+
+			/** A sample whose token data is unusable stays plain. */
+			#highlight(code) {
+				unpaint(this);
+				try {
+					const text = code?.firstChild;
+					if (text) {
+						paint(
+							this,
+							decode(code.dataset.tokens).map(([group, start, end]) => {
+								const range = new Range();
+								range.setStart(text, start);
+								range.setEnd(text, end);
+								return [group, range];
+							}),
+						);
+					}
+				} catch {
+					unpaint(this);
+				}
+			}
+
+
+			/** Keep the code a named, focusable region only while it scrolls: a tab stop is for something to scroll. */
+			#watchOverflow(pre, name) {
+				const fit = () => {
+					if (pre.scrollWidth > pre.clientWidth) {
+						pre.setAttribute("tabindex", "0");
+						if (name?.id) {
+							pre.setAttribute("role", "region");
+							pre.setAttribute("aria-labelledby", name.id);
+						}
+					} else {
+						pre.removeAttribute("tabindex");
+						pre.removeAttribute("role");
+						pre.removeAttribute("aria-labelledby");
+					}
+				};
+				document.fonts?.ready.then(fit);
+				this.#observer?.disconnect();
+				if (typeof ResizeObserver === "undefined") return;
+				this.#observer = new ResizeObserver(fit);
+				this.#observer.observe(pre);
+			}
+		}
+
+		if (!customElements.get("norn-code-block")) customElements.define("norn-code-block", CodeBlock);
+	}
+</script>

package/index.js

@@ -0,0 +1,100 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import path from "node:path";
+
+import { addLanguages, tokenize } from "./tokenize.js";
+
+/**
+ * Ranges by language and code, for the life of the process. The code is the key, so a watch-mode rebuild with changed code tokenizes again.
+ * Holds at most `CACHE_LIMIT` samples and drops the oldest first.
+ */
+const cache = new Map();
+const CACHE_LIMIT = 1000;
+
+/**
+ * Add languages beyond the defaults.
+ *
+ * @param {...import("shiki/core").LanguageRegistration[]} languages - Shiki language registrations, such as the default export of `@shikijs/langs/rust`
+ */
+export function loadLanguages(...languages) {
+	addLanguages(languages.flat());
+	cache.clear();
+}
+
+/** Absolute glob-safe path to `components/norn-code-block.webc`, for the project's WebC `components` list. */
+export const codeBlock = path.join(import.meta.dirname, "components", "norn-code-block.webc").split(path.sep).join("/");
+
+/**
+ * Tokenize code with Shiki into highlight ranges, in the compact form `data-tokens` carries (see `encodeRanges`).
+ *
+ * @param {string} code
+ * @param {string} [language]
+ * @returns {string | undefined} JSON `[groups, numbers]`; undefined when the language isn't loaded or nothing matched
+ */
+export function tokenRanges(code, language = "") {
+	const key = `${language}\0${code}`;
+	if (cache.has(key)) return cache.get(key);
+	const found = tokenize(code, language);
+	const ranges = found && encodeRanges(found);
+	if (cache.size >= CACHE_LIMIT) cache.delete(cache.keys().next().value);
+	cache.set(key, ranges);
+	return ranges;
+}
+
+/**
+ * Write ranges in the compact `data-tokens` form: `[groups, numbers]`, the group names once each, in order of first use,
+ * then three numbers per range: the group's index in `groups`, the gap from the end of the range before (or from 0), and the length.
+ *
+ * @param {[string, number, number][]} ranges - `[group, start, end]`, ordered and apart
+ * @returns {string}
+ */
+function encodeRanges(ranges) {
+	const groups = [];
+	const numbers = [];
+	let previousEnd = 0;
+	for (const [group, start, end] of ranges) {
+		if (!groups.includes(group)) groups.push(group);
+		numbers.push(groups.indexOf(group), start - previousEnd, end - start);
+		previousEnd = end;
+	}
+	return JSON.stringify([groups, numbers]);
+}
+
+/**
+ * Read a `tokenRanges` string, the `data-tokens` value, back into `[group, start, end][]` character offsets.
+ *
+ * @param {string | undefined} value - The compact form; undefined, as `tokenRanges` returns for no ranges, reads as none
+ * @returns {[string, number, number][]}
+ * @throws {TypeError} When the value is not the compact form, naming what is wrong
+ */
+export function decodeRanges(value) {
+	if (value === undefined) return [];
+	if (typeof value !== "string") throw new TypeError(`decodeRanges takes a string, not ${typeof value}.`);
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		throw new TypeError("decodeRanges: the value is not JSON.");
+	}
+	const [groups, numbers] = Array.isArray(parsed) ? parsed : [];
+	if (parsed?.length !== 2 || !Array.isArray(groups) || !Array.isArray(numbers)) throw new TypeError("decodeRanges: the value is not a group table and a list of numbers.");
+	if (!groups.every((group) => typeof group === "string")) throw new TypeError("decodeRanges: the group table holds group names only.");
+	if (numbers.length % 3) throw new TypeError("decodeRanges: the list of numbers is not a multiple of three long.");
+	const ranges = [];
+	let end = 0;
+	for (let at = 0; at < numbers.length; at += 3) {
+		const [index, gap, length] = numbers.slice(at, at + 3);
+		if (!Number.isInteger(index) || !Object.hasOwn(groups, index)) throw new TypeError(`decodeRanges: range ${at / 3} names group ${index}, which the table lacks.`);
+		if (!Number.isInteger(gap) || gap < 0) throw new TypeError(`decodeRanges: range ${at / 3} has gap ${gap}, not a whole number of 0 or more.`);
+		if (!Number.isInteger(length) || length < 1) throw new TypeError(`decodeRanges: range ${at / 3} has length ${length}, not a whole number of 1 or more.`);
+		const start = end + gap;
+		end = start + length;
+		ranges.push([groups[index], start, end]);
+	}
+	return ranges;
+}

package/markdown.js

@@ -0,0 +1,25 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/*
+ * The Markdown add-on. It writes the `<norn-code-block>` tag an author would write by hand
+ * and no text of its own: the component's slot fallbacks and `componentStrings` supply every string.
+ */
+
+/**
+ * markdown-it amend: render fenced code as `<norn-code-block>`, with the fence's first word as its `language`.
+ * It fills no slots: the component names the code ("js code") and its copy button, and takes the button texts from the site's `componentStrings`, then English.
+ *
+ * @param {import("markdown-it")} md
+ */
+export function highlightFences(md) {
+	md.renderer.rules.fence = (tokens, idx) => {
+		const { content, info } = tokens[idx];
+		const language = info.trim().split(/\s+/)[0];
+		return `<norn-code-block @code="${md.utils.escapeHtml(content)}" @language="${md.utils.escapeHtml(language)}"></norn-code-block>\n`;
+	};
+}

package/package.json

@@ -1,6 +1,57 @@
 {
-  "name": "@allons-y/webc-code-sample",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@allons-y/webc-code-sample",
+	"version": "0.1.0-beta.1",
+	"description": "WebC code sample component with build-time syntax highlighting and no highlighter shipped to the browser.",
+	"license": "MPL-2.0",
+	"author": "Cassondra Roberts <castastrophe@users.noreply.github.com> (https://allons-y.studio)",
+	"homepage": "https://github.com/allonsy-studio/webc-resources/tree/main/packages/webc-code-sample#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/allonsy-studio/webc-resources.git",
+		"directory": "packages/webc-code-sample"
+	},
+	"bugs": {
+		"url": "https://github.com/allonsy-studio/webc-resources/issues"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"type": "module",
+	"exports": {
+		".": "./index.js",
+		"./markdown": "./markdown.js",
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"components/",
+		"index.js",
+		"markdown.js",
+		"tokenize.js",
+		"LICENSE",
+		"README.md"
+	],
+	"scripts": {
+		"prepack": "node ../../scripts/build-components.js webc-code-sample"
+	},
+	"devDependencies": {
+		"markdown-it": "^15.0.2"
+	},
+	"peerDependencies": {
+		"@11ty/eleventy": "^3.0.0",
+		"@11ty/eleventy-plugin-webc": "^0.11.0",
+		"@allons-y/webc-patterns": "^0.1.0-beta.0"
+	},
+	"keywords": [
+		"webc",
+		"eleventy",
+		"11ty"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"dependencies": {
+		"@shikijs/langs": "^4.5.0",
+		"shiki": "^4.5.0"
+	}
+}

package/tokenize.js

@@ -0,0 +1,231 @@
+/*
+ * SPDX-License-Identifier: MPL-2.0
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/** Shiki tokenizing behind `tokenRanges`. Internal: the package exports map leaves it out. */
+
+import bash from "@shikijs/langs/shellscript";
+import css from "@shikijs/langs/css";
+import diff from "@shikijs/langs/diff";
+import html from "@shikijs/langs/html";
+import javascript from "@shikijs/langs/javascript";
+import json from "@shikijs/langs/json";
+import markdown from "@shikijs/langs/markdown";
+import typescript from "@shikijs/langs/typescript";
+import yaml from "@shikijs/langs/yaml";
+import { createHighlighterCoreSync } from "shiki/core";
+import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
+
+/** Shiki needs a theme to tokenize. The colors come from the page's CSS, so this one has none. */
+const THEME = { name: "norn", type: "light", fg: "#000", bg: "#fff", settings: [] };
+
+const highlighter = createHighlighterCoreSync({
+	themes: [THEME],
+	langs: [bash, css, diff, html, javascript, json, markdown, typescript, yaml],
+	engine: createJavaScriptRegexEngine(),
+});
+
+/**
+ * Add Shiki languages to the highlighter.
+ *
+ * @param {import("shiki/core").LanguageRegistration[]} languages
+ */
+export function addLanguages(languages) {
+	highlighter.loadLanguageSync(languages);
+}
+
+/** Highlight group by TextMate scope prefix, most specific first. The deepest scope of a token that matches a prefix decides. */
+const SCOPES = [
+	["comment", "comment"],
+	["punctuation.definition.comment", "comment"],
+	["punctuation.definition.string", "string"],
+	["string.unquoted", undefined],
+	["string", "string"],
+	["markup.inserted", "string"],
+	["constant.character.escape.line-continuation", "punctuation"],
+	["constant.numeric", "number"],
+	["constant.language", "number"],
+	["keyword.operator", "punctuation"],
+	["keyword", "keyword"],
+	["storage", "keyword"],
+	["entity.name.tag", "keyword"],
+	["markup.heading", "keyword"],
+	["entity.name.function", "function"],
+	["entity.name.command", "function"],
+	["entity.name.type", "function"],
+	["entity.name.class", "function"],
+	["entity.other.attribute-name", "function"],
+	["entity.other.inherited-class", "function"],
+	["support.function", "function"],
+	["support.class", "function"],
+	["support.type.property-name", "function"],
+	["meta.object-literal.key", "function"],
+	["punctuation", "punctuation"],
+];
+
+/** The highlight group of a stack of scopes, from the outermost to the deepest. A prefix with no group, such as an unquoted word, stops the search: it stays plain. */
+const groupOf = (scopes) => {
+	for (const { scopeName } of scopes.toReversed()) {
+		const match = SCOPES.find(([prefix]) => scopeName === prefix || scopeName.startsWith(`${prefix}.`));
+		if (match) return match[1];
+	}
+	return undefined;
+};
+
+/** Languages that read as shell commands, and the ones whose lines are commands only after a `$ ` prompt. */
+const SHELL = new Set(["sh", "bash", "shell"]);
+const SESSION = new Set(["shell-session", "sh-session", "shellsession"]);
+
+/** Words that start a command list again: after one, the next word is a command. */
+const CONTROL = new Set(["if", "then", "else", "elif", "do", "while", "until", "!", "time"]);
+
+/** Words made only of operator characters: a pipe or a list separator starts a command, a redirect does not. */
+const OPERATOR = /^[<>|&;()0-9]*[<>|&;()]+$/;
+const ASSIGNMENT = /^[A-Za-z_]\w*=/;
+const SEPARATOR = /^(\|\|?|&&|&|;|\(|\|&)$/;
+
+/** Whether a line ends with a lone backslash, so its command goes on in the next line. */
+const continues = (line) => line.trimEnd().split(/\s+/).at(-1) === "\\";
+
+
+/**
+ * Tokenize code with Shiki into highlight ranges, ordered and apart: each range starts at or after the end of the one before.
+ *
+ * @param {string} code
+ * @param {string} [language]
+ * @returns {[string, number, number][] | undefined} `[group, start, end]` character offsets; undefined when the language isn't loaded or nothing matched
+ */
+export function tokenize(code, language = "") {
+	const session = SESSION.has(language);
+	const lang = session ? "bash" : language;
+	if (!lang || !highlighter.getLoadedLanguages().includes(lang)) return undefined;
+	let ranges = [];
+	// No time limit: Shiki tokenizes each line twice, and a limit that stops one pass early, as on a busy machine, breaks the explanation.
+	const { tokens } = highlighter.codeToTokens(code, { lang, theme: THEME.name, includeExplanation: "scopeName", tokenizeTimeLimit: 0 });
+	for (const lineTokens of tokens) {
+		for (const token of lineTokens) {
+			let at = token.offset;
+			for (const { content, scopes } of token.explanation ?? []) {
+				const group = groupOf(scopes);
+				const end = at + content.length;
+				if (group && content.trim()) {
+					const previous = ranges.at(-1);
+					if (previous?.[0] === group && previous[2] === at) previous[2] = end;
+					else ranges.push([group, at, end]);
+				}
+				at = end;
+			}
+		}
+	}
+	if (SHELL.has(language) || session) ranges = shellWords(code, ranges, session);
+	return ranges.length ? ranges : undefined;
+}
+
+/**
+ * Give the words of each shell line their roles over Shiki's ranges: the command is a `function`, the first plain word after it a `keyword` (the subcommand), a flag a `flag`, and any other word a `string`.
+ * Comments, quoted strings, and variables keep what Shiki gave them. A `$ ` prompt stays punctuation.
+ *
+ * @param {string} code
+ * @param {[string, number, number][]} ranges - Shiki's ranges, in order
+ * @param {boolean} session - Only lines that start with a `$ ` prompt are commands
+ * @returns {[string, number, number][]}
+ */
+function shellWords(code, ranges, session) {
+	const roles = [];
+	if (session) {
+		// Output lines are plain: keep Shiki's ranges only on the lines of a command, which start with a prompt and go on while a line ends with a backslash.
+		let at = 0;
+		let running = false;
+		const kept = new Set();
+		for (const line of code.split("\n")) {
+			const command = running || /^\s*\$\s/.test(line);
+			if (command) kept.add(at);
+			running = command && continues(line);
+			at += line.length + 1;
+		}
+		const lineStart = (offset) => code.lastIndexOf("\n", offset - 1) + 1;
+		ranges = ranges.filter(([, start]) => kept.has(lineStart(start)));
+	}
+	const within = (at, groups) => ranges.some(([group, start, end]) => groups.includes(group) && at >= start && at < end);
+	let command = true;
+	let sub = true;
+	let dashes = false;
+	let continued = false;
+	let offset = 0;
+	for (const line of code.split("\n")) {
+		const words = [...line.matchAll(/\S+/g)];
+		const prompted = /^\s*\$\s/.test(line);
+		const continuing = continued;
+		if (!continuing) {
+			command = !session || prompted;
+			sub = false;
+			dashes = false;
+		}
+		continued = (!session || prompted || continuing) && continues(line);
+		for (const [index, match] of words.entries()) {
+			const [word] = match;
+			const start = offset + match.index;
+			const end = start + word.length;
+			if (within(start, ["comment", "string"])) {
+				if (within(start, ["comment"])) break;
+				continue;
+			}
+			if (index === 0 && prompted && word === "$") {
+				roles.push(["punctuation", start, end]);
+				continue;
+			}
+			if (!command && session && !prompted && !continuing) continue;
+			if (SEPARATOR.test(word)) {
+				command = true;
+				continue;
+			}
+			if (OPERATOR.test(word) || word === "\\") continue;
+			if (command && ASSIGNMENT.test(word)) {
+				const equals = word.indexOf("=");
+				const value = word.slice(equals + 1);
+				roles.push(["punctuation", start + equals, start + equals + 1]);
+				if (value && !/^["']/.test(value)) roles.push([/^\d+$/.test(value) ? "number" : "string", start + equals + 1, end]);
+				continue;
+			}
+			if (word.startsWith("$")) {
+				if (!command) roles.push(["string", start, end]);
+				continue;
+			}
+			if (command) {
+				if (CONTROL.has(word)) {
+					roles.push(["keyword", start, end]);
+				} else {
+					roles.push(["function", start, end]);
+					command = false;
+					sub = false;
+					dashes = false;
+				}
+			} else if (word === "--") {
+				dashes = true;
+				roles.push(["punctuation", start, end]);
+			} else if (word.startsWith("-") && word.length > 1) {
+				const equals = word.indexOf("=");
+				const stop = equals === -1 ? end : start + equals;
+				roles.push(["flag", start, stop]);
+				if (equals !== -1) roles.push(["punctuation", stop, stop + 1]);
+				if (equals !== -1 && equals + 1 < word.length) roles.push(["string", start + equals + 1, end]);
+			} else if (!sub && !dashes) {
+				roles.push(["keyword", start, end]);
+				sub = true;
+			} else {
+				roles.push(["string", start, end]);
+			}
+		}
+		offset += line.length + 1;
+	}
+	// The roles replace whatever Shiki gave the same characters.
+	const cut = ranges.flatMap(([group, start, end]) => {
+		let pieces = [[start, end]];
+		for (const [, from, to] of roles) pieces = pieces.flatMap(([a, b]) => (to <= a || from >= b ? [[a, b]] : [[a, Math.min(b, from)], [Math.max(a, to), b]].filter(([x, y]) => y > x)));
+		return pieces.map(([a, b]) => [group, a, b]);
+	});
+	return [...cut, ...roles].sort((a, b) => a[1] - b[1]);
+}