galath 1.0.2

package/AGENTS.md

@@ -0,0 +1 @@
+- External npm dependencies are forbidden due to possibley supply chain attacks

package/README.md

@@ -0,0 +1,206 @@
+# Galath Strong Core
+
+An XML manifesto for the age of AI.
+
+Galath is a small language for web applications. It treats UI, state, events,
+commands, components, imports, and instance data as explicit XML structure.
+The goal is not nostalgia. The goal is a stronger substrate for humans and
+machines to read, edit, verify, and extend.
+
+```xml
+<component name="counter" tag="x-counter">
+  <model>
+    <signal name="count" value="0" />
+    <signal name="step" value="1" />
+  </model>
+
+  <view>
+    <button on:click="set('count', count + step)">+</button>
+    <span>Count: {count}</span>
+    <input type="number" bind:value="step" />
+  </view>
+</component>
+```
+
+## The Claim
+
+AI does not need less structure. It needs better structure.
+
+The web became powerful by accepting strings everywhere: HTML strings, CSS
+strings, JavaScript strings, JSON strings, template strings, build config
+strings. That freedom made software easy to start and hard to reason about.
+Every agent, editor, linter, compiler, and reviewer must infer the shape of
+the program from conventions.
+
+Galath makes the shape visible.
+
+```xml
+<model> declares state.</model>
+<view> declares the interface.</view>
+<controller> names behavior.</controller>
+<commandset> names intent.</commandset>
+<instance> carries structured data.</instance>
+<import> composes documents.</import>
+```
+
+This is the strong core: a small number of explicit concepts, each with a
+clear place in the document.
+
+## Principles
+
+**Structure before cleverness.** A Galath document should be inspectable by a
+person, a browser, a test, or an AI agent without first reverse-engineering a
+framework's private conventions.
+
+**State is named.** Dynamic values live in signals or in the XML instance tree.
+When something changes, the path to that change is visible.
+
+**Behavior is addressable.** Inline event code exists, but durable behavior can
+be named in controllers and commands.
+
+**Composition is document-level.** Features can live in separate XML files and
+arrive through `<import>`, not through a bundler ceremony.
+
+**The runtime stays small.** Galath has no external npm dependencies. The
+project favors readable platform code over supply-chain reach.
+
+**Escapes are explicit.** Expressions are JavaScript expressions in a scoped
+context. Paths are a strict XPath-like subset. When the language crosses into
+JavaScript, it does so plainly.
+
+## Why XML Now
+
+XML is not just angle brackets. XML is a contract:
+
+- elements have names;
+- attributes have names;
+- nesting is explicit;
+- documents are parseable before execution;
+- namespaces let languages grow without guessing;
+- source can be transformed without pretending it is text.
+
+That matters in the age of AI because agents are better collaborators when the
+program has visible grammar. A model can add a chapter, inspect a component,
+trace a signal, or rewrite a command without guessing which string is code,
+which string is markup, and which string is data.
+
+```xml
+<repeat ref="/todos/todo" as="todo">
+  <button on:click="deleteNode($todo)">Delete</button>
+  <text value="$todo/@text" />
+</repeat>
+```
+
+The data path is visible. The local variable is visible. The event boundary is
+visible. This is what strong markup buys back.
+
+## What Galath Includes
+
+- Custom elements from `<component>`.
+- Reactive `<signal>` values.
+- Derived `<computed>` values.
+- XML instance trees with path selection.
+- Interpolation with `{expr}`.
+- Two-way bindings with `bind:value` and `bind:checked`.
+- Event handlers with `on:*`.
+- Named controller actions.
+- Command sets.
+- Reusable data templates.
+- XML imports.
+- Attached behaviors.
+- Lifecycle hooks with `<on:mount>` and `<on:unmount>`.
+- DOM morphing to preserve focus and form state.
+
+## Run The Playground
+
+```sh
+npm run serve
+```
+
+Then open the served URL. The playground is the main documentation surface and
+is itself written in Galath.
+
+No build step is required for the playground. The browser loads local modules
+through an import map.
+
+## Minimal Boot
+
+```html
+<div id="mount"></div>
+
+<script type="application/xml" id="galath-source">
+  <galath version="1.0">
+    <component name="hello" tag="x-hello">
+      <model>
+        <signal name="name" value="World" />
+      </model>
+      <view>
+        <h1>Hello, {name}.</h1>
+      </view>
+    </component>
+
+    <application name="app">
+      <x-hello />
+    </application>
+  </galath>
+</script>
+
+<script type="module">
+  import { boot } from 'galath/boot';
+
+  await boot({
+    source: document.getElementById('galath-source').textContent,
+    mount: document.getElementById('mount'),
+  });
+</script>
+```
+
+## The Strong Core Contract
+
+Galath should remain small enough to understand and structured enough to grow.
+
+It should be possible to answer these questions by reading the document:
+
+- What state exists?
+- What data tree exists?
+- What renders?
+- What changes state?
+- What paths are read or written?
+- What components are imported?
+- What behavior is named?
+
+If a language can answer those questions directly, AI tools can help without
+turning the codebase into mud.
+
+## Not A Framework Fashion
+
+Galath is not trying to hide the platform. It uses the platform:
+
+- Custom Elements for component boundaries.
+- DOMParser and XMLSerializer for documents.
+- `fetch()` for imports.
+- native events for interaction.
+- import maps for local modules.
+
+The language is a thin, explicit layer over the browser. Its job is to preserve
+the structure that ordinary web code too often throws away.
+
+## The Manifesto
+
+We choose documents over blobs.
+
+We choose named state over ambient mutation.
+
+We choose paths over guesswork.
+
+We choose explicit imports over invisible build magic.
+
+We choose small runtimes over dependency gravity.
+
+We choose a language an AI can inspect without hallucinating the shape of the
+program.
+
+We choose XML not because it is old, but because it is still one of the few
+formats honest enough to say what a program is made of.
+
+That is Galath Strong Core.

package/TODO.md

@@ -0,0 +1,140 @@
+# Galath - TODO
+
+Items left for follow-up. None are blocking; the runtime, the playground, and
+the reference demo all work as shipped. These are improvements that would make
+Galath more capable, more polished, or more productive for authors.
+
+The list is grouped by who can pick it up. The "Sonnet-friendly" pile is
+deliberately scoped: clear inputs, clear outputs, low ambiguity.
+
+---
+
+## Sonnet-friendly (good first tasks)
+
+### Documentation
+
+- [ ] **Write `packages/galath/README.md`.** Cover: install (none), import
+  map setup, two-line boot, link to playground, link to seed.html, list of
+  features. Keep under 300 lines.
+- [ ] **Write `docs/PATHS.md`** documenting the path grammar. Include a
+  cheat-sheet for `/foo/bar`, `/foo/bar[@id=x]`, `$todo/@text`, `/text()`,
+  wildcard `*`. Show what's unsupported (descendant `//`, function calls
+  beyond `text()`, multi-step predicates).
+- [ ] **Write `docs/EXPRESSIONS.md`** documenting which helpers are in
+  scope (`uid`, `select`, `valueOf`, `set`, `attr`, `deleteNode`,
+  `setNode`, `$event`, all signal names, all locals). Note the JS escape
+  hatch for anything else.
+
+### Playground polish
+
+- [ ] **Add a "Run" button** to each chapter's source listing that opens
+  the snippet in a new tab as a complete HTML file. Implementation: a
+  command that copies the snippet into a Blob and `URL.createObjectURL`,
+  with the standard import map / boot wrapper.
+- [ ] **Add basic syntax highlighting** to `<pre class="xes-code">`
+  blocks. Either ship a tiny tokenizer in `playground/components/` or
+  add a `use:highlight` behavior. Keep it under 150 lines; we don't
+  want a full Prism dependency.
+- [ ] **Add a toggle** to switch between the "narrated" chapter view
+  (current) and a "code-only" view that hides the docs card. Useful for
+  experienced readers.
+- [ ] **Keyboard navigation**: left/right arrows move between chapters.
+  Implement as a `keydown` listener in the playground's `<on:mount>`.
+
+### Chapter improvements
+
+- [ ] **02-signals**: add a "computed chain" demo - `a -> b -> c` where
+  each is computed from the previous. Explain dependency tracking is
+  explicit (via `from=`).
+- [ ] **04-bindings**: add `bind:` examples for `<select>` and date
+  inputs.
+- [ ] **05-lists**: add an `index`-based example using the implicit
+  `index` local that `<repeat>` provides.
+- [ ] **06-commands**: add a `<command shortcut="ctrl+s">` example. (See
+  language work below - shortcuts are not yet implemented.)
+- [ ] **09-behaviors**: write a "build your own behavior" subsection
+  showing how to register a new behavior via
+  `language.behaviors.set(...)` from a feature plugin.
+
+### Tests
+
+- [ ] **Add a Playwright smoke test** that boots `index.html`, clicks
+  through each chapter, and asserts there's no console error.
+- [ ] **Add unit tests for path parsing** in `packages/galath/test/`
+  covering the cases listed in `docs/PATHS.md`.
+- [ ] **Add unit tests for `morph.js`** covering: focus preservation,
+  child swap by tag, attribute removal, custom-element child skip.
+
+---
+
+## Larger pieces (Opus-y, but not urgent)
+
+### Language features
+
+- [x] **`<slot>` support** so components can accept inline children. This
+  removes the "pass code in a signal name" workaround in `code-card`.
+  Touches `component.js` (capture inline children before stamping
+  xesRoot) and `rendering.js` (resolve `<slot>` against the captured
+  fragment, fall back to default content).
+- [x] **Cross-component scope reads.** Add a directive like
+  `bind:from-parent="signalName"` that lets a child read a signal in its
+  parent component. Walk up via `closest('[data-xes-root]')`.
+- [x] **Keyed `<repeat>` / `<items>`**. Today the renderer relies on
+  positional matching plus `morph.js`. With reorders this is fine but
+  slower than necessary. Add `key="@id"` and a simple keyed reconciler.
+- [x] **`<switch on="expr"><case value="...">...</case><default>...</default></switch>`**.
+  Cleaner than chained `<if>`. Lower in `rendering.js`.
+- [x] **Async operations**: `<fetch url="..." into="signal">` and
+  `<command async>`. Useful for real-world data loading without dropping
+  into `<eval>`.
+- [x] **Form validation**: re-introduce XForms `<bind constraint="..."
+  required="..." type="...">` and surface validation state to inputs.
+
+### Tooling
+
+- [ ] **VS Code extension** for `.xml` syntax in the Galath dialect
+  (color the directives, autocomplete bindings, hover docs).
+- [ ] **A static linter** that walks Galath sources and reports common
+  mistakes: unknown component tags, dead `<command name>` (never
+  referenced), unbound `bind:` paths against the declared instance tree.
+- [ ] **Source map** from rendered HTML elements back to the source
+  XML line. Useful for in-browser DevTools-like inspection.
+
+### Performance
+
+- [x] **Granular signal -> render mapping**. Today any signal change
+  re-renders the whole component view. Track which bindings depend on
+  which signals (we already collect bindings during render); re-run only
+  the affected expressions on update.
+  
+### Ecosystem
+
+- [ ] **A few real apps** built on Galath - a markdown editor, a kanban
+  board, a small SPA that talks to an HTTP API. They will surface holes
+  in the language we don't see from the playground.
+- [ ] **Standard component library** in `packages/galath-ui/` -
+  consistent buttons, modal, table, form. Optional; depends only on the
+  base runtime.
+
+---
+
+## Open questions
+
+- Should component instances persist across `<if>` toggles, or always
+  re-mount? Today they re-mount. Persisting would need a "keep alive"
+  directive and a place to stash detached instances.
+  answer: follow the web-component approach, remount
+- Should `<text value="...">` accept template syntax like `{count}` or
+  always be a single path? Right now it's a single path; mixing would
+  collide with the path grammar.
+  answer: no collisions, keep it simple.
+- What do we do about CSS-in-Galath? Today `<style>` is a global
+  scoped sheet. Should we accept `<style scoped="false">` or
+  `<style :where>` for opt-in scope rules?
+  answer: CSS must be external to Galath, provided by a powerful build system like CSS.
+  
+## Not Interested / Cancelled
+
+- [-] **Compile views**. Pre-compile `<view>` to a JS function at
+  registerComponent time so renders skip the XML walk. Big change; only
+  worth it if profiling shows the renderer is a bottleneck.

package/index.html

@@ -0,0 +1,188 @@
+<!doctype html>
+<!--
+  index.html
+  ==========
+
+  The Galath playground entry point. A small shell:
+
+    1. Pulls in local Bootstrap CSS + Bootstrap Icons (see node_modules/galath-css).
+    2. Declares a native browser <importmap> so `import 'galath'` resolves to
+       packages/galath via a symlink in node_modules.
+    3. Declares one Galath source document. The document is mostly
+       <import src="..."/> lines that pull in chapter components and the
+       playground shell.
+    4. Boots Galath with two lines of JavaScript.
+
+  The whole tutorial is written in Galath itself - dogfooding the language.
+  Every chapter is a separate XML file under ./playground/chapters/, kept
+  small and focused. To add another chapter:
+
+    a. Create ./playground/chapters/12-my-feature.xml that defines a
+       <component name="chapter-myFeature" tag="x-chapter-myFeature">.
+    b. Add an <import src="./playground/chapters/12-my-feature.xml"/> below.
+    c. Add a <chapter id="myFeature" .../> entry in app.xml.
+    d. Add an <if test="activeChapter === 'myFeature'"> branch in app.xml.
+
+  To run:
+    npx serve .         (or `python3 -m http.server 8080`)
+    open http://localhost:8080/
+
+  No build step. No bundler. No transpiler. Just the browser.
+-->
+<html lang="en" data-bs-theme="dark">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Galath Playground</title>
+
+  <!-- Local stylesheets - works offline. -->
+  <link href="./node_modules/galath-css/css/bootstrap.min.css" rel="stylesheet">
+  <link href="./node_modules/galath-css/css/bootstrap-icons.min.css" rel="stylesheet">
+
+  <!--
+    Native browser import map. `galath/boot` is the convenience entry that
+    plugs every standard feature in and starts the language. The mapping
+    goes through ./node_modules/galath -> packages/galath, set up as a
+    symlink so we don't have to publish to a registry to develop locally.
+  -->
+  <script type="importmap">
+    {
+      "imports": {
+        "galath": "./node_modules/galath/src/index.js",
+        "galath/boot": "./node_modules/galath/src/boot.js"
+      }
+    }
+  </script>
+
+  <style>
+    /*
+      Page chrome. Component-internal styles live inside their components'
+      <style> blocks where they get auto-scoped to the component root.
+    */
+    :root {
+      --xes-shell:  #06101f;
+      --xes-line:   rgba(255, 255, 255, .12);
+      --xes-card:   rgba(255, 255, 255, .045);
+      --xes-card-2: rgba(255, 255, 255, .022);
+    }
+    body {
+      min-height: 100vh;
+      background:
+        radial-gradient(circle at top left,  rgba(13, 202, 240, .14), transparent 34rem),
+        radial-gradient(circle at top right, rgba(255, 193, 7, .08),  transparent 28rem),
+        linear-gradient(180deg, #040812, var(--xes-shell));
+    }
+    .xes-card        { background: linear-gradient(180deg, var(--xes-card), var(--xes-card-2)); border: 1px solid var(--xes-line); box-shadow: 0 1rem 3rem rgba(0,0,0,.22); }
+    .xes-code        { max-height: 26rem; overflow: auto; font-size: .8rem; background: rgba(0,0,0,.34); border: 1px solid var(--xes-line); }
+    .xes-nav-link    { width: 100%; text-align: left; color: var(--bs-body-color); background: transparent; border: 0; }
+    .xes-nav-link:hover { background-color: rgba(255,255,255,.07); }
+    .xes-nav-link.active { background-color: rgba(13,202,240,.16); box-shadow: inset 3px 0 0 var(--bs-info); color: var(--bs-info-text-emphasis); }
+    .xes-pill        { border: 1px solid var(--xes-line); background-color: rgba(255,255,255,.045); }
+    .xes-tiny        { font-size: .78rem; }
+    .xes-drop-hint   { outline: 1px dashed rgba(13, 202, 240, .35); outline-offset: .35rem; }
+    .xes-dragging    { opacity: .5; }
+    .xes-sidebar     { background: rgba(0,0,0,.18); }
+
+    /*
+      Syntax highlighting for the source listings. Tokens come from the
+      tiny tokenizer in playground/components/highlighter.js.
+    */
+    .xes-code .hl-cm  { color: #6c757d; font-style: italic; }
+    .xes-code .hl-cd  { color: #c792ea; }
+    .xes-code .hl-pn  { color: #6c757d; }
+    .xes-code .hl-tn  { color: #6cb4ee; font-weight: 600; }
+    .xes-code .hl-an  { color: #f0c674; }
+    .xes-code .hl-av  { color: #98c379; }
+    .xes-code .hl-itp { color: #ffb454; font-weight: 600; }
+
+    /*
+      Code-only view. The sidebar toggle flips a `xes-code-only` class on
+      the playground container. Every chapter follows the same docs/source
+      layout - a `.row.g-4` whose first `.col-lg-6` is the "How it works"
+      narration and second is the source listing - so a structural rule
+      hides docs and widens the source listing without touching each chapter.
+    */
+    .xes-code-only .row.g-4 > .col-lg-6:first-child { display: none; }
+    .xes-code-only .row.g-4 > .col-lg-6:last-child  { flex: 0 0 100%; max-width: 100%; }
+
+    /* Loading state until galath finishes booting. */
+    #mount:empty::before {
+      content: "Loading Galath playground...";
+      display: block;
+      padding: 2rem;
+      color: rgba(255,255,255,.6);
+    }
+  </style>
+</head>
+<body>
+  <div id="mount"></div>
+
+  <!--
+    The Galath source document. Almost everything is in imports. Adding
+    a chapter is one line here + one line in playground/app.xml + the
+    actual chapter file.
+  -->
+  <script type="application/xml" id="galath-source">
+    <galath version="1.0">
+      <!-- shared building blocks first so chapters can reference them -->
+      <import src="./playground/components/chapter-shell.xml" />
+
+      <!-- one chapter file each, in tutorial order -->
+      <import src="./playground/chapters/01-welcome.xml" />
+      <import src="./playground/chapters/02-signals.xml" />
+      <import src="./playground/chapters/03-instance.xml" />
+      <import src="./playground/chapters/04-bindings.xml" />
+      <import src="./playground/chapters/12-expressions.xml" />
+      <import src="./playground/chapters/13-paths.xml" />
+      <import src="./playground/chapters/05-lists.xml" />
+      <import src="./playground/chapters/06-commands.xml" />
+      <import src="./playground/chapters/07-controller.xml" />
+      <import src="./playground/chapters/08-events.xml" />
+      <import src="./playground/chapters/09-behaviors.xml" />
+      <import src="./playground/chapters/10-components.xml" />
+      <import src="./playground/chapters/11-imports.xml" />
+
+      <!-- the shell that ties chapters together -->
+      <import src="./playground/app.xml" />
+
+      <!-- entry point: just instantiate the shell -->
+      <application name="playground">
+        <x-playground />
+      </application>
+    </galath>
+  </script>
+
+  <!--
+    Boot. Two lines: read the source from the script tag, hand it to
+    galath, watch the page light up. `boot` returns the language object
+    so we expose it on `window.galath` for console exploration.
+  -->
+  <script type="module">
+    import { boot } from 'galath/boot';
+    import { attachHighlighter } from './playground/components/highlighter.js';
+    import { attachRunSnippet } from './playground/components/run-snippet.js';
+
+    try {
+      attachRunSnippet();
+      window.galath = await boot({
+        source: document.getElementById('galath-source').textContent,
+        mount:  document.getElementById('mount'),
+      });
+      attachHighlighter(document.getElementById('mount'));
+    } catch (error) {
+      // If the boot itself crashed, the error never reaches the user
+      // through the normal rendering path. Surface it loudly.
+      const mount = document.getElementById('mount');
+      mount.innerHTML = `
+        <div class="container-xxl py-5">
+          <div class="alert alert-danger">
+            <h2 class="h5"><i class="bi bi-exclamation-triangle me-2"></i>Galath failed to boot</h2>
+            <pre class="mb-0">${String(error?.stack || error)}</pre>
+          </div>
+        </div>
+      `;
+      throw error;
+    }
+  </script>
+</body>
+</html>