Skip to content

Integrate lgtmd docs site and pin SDK to 0.3.0 #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
softmarshmallow wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Integrate lgtmd docs site and pin SDK to 0.3.0 #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,8 @@ boundaries. The current Editor still depends on egui and is not a public kernel

Keep N3 as one application crate. Its documentation adapter consumes the portable
[lgtmd SDK](https://github.com/lgtmd/lgtmd), maintained in its own repository.
N3 pins an exact Git revision until a registry release is ready. The tested
boundary separates application replay from document composition and publication;
it does not make the editor a public kernel. Keep N3's replay, renderer, scenarios,
N3 pins the exact reviewed crates.io release `lgtmd = "=0.3.0"`. The tested boundary separates application replay from document composition
and publication; it does not make the editor a public kernel. Keep N3's replay, renderer, scenarios,
fixtures, and guide outputs here. SDK authoring, compiler/store changes, portable
Rust/Node examples, and SDK verification belong in lgtmd. Prefer focused modules
over further speculative crates or APIs. See
Expand Down
5 changes: 3 additions & 2 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ wgpu = "30.0.1"
winit = "=0.30.13"

[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
lgtmd = { git = "https://github.com/lgtmd/lgtmd", rev = "8828c41eaf7fbb002044aea9f8bfd4a06ba76168" }
lgtmd = "=0.3.0"
alacritty_terminal = "=0.26.0"
egui-winit = { version = "=0.36.2", default-features = false, features = [
"clipboard",
Expand Down
2 changes: 1 addition & 1 deletion TODO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ and document the implemented behavior in the executable user guide.
| Paired selection in 2D | **Deferred:** consider verified front/back vertex pairing in aligned views; exact geometry does not prove selection intent. See [RFC 0001](rfcs/0001-paired-selection-in-2d.md). |
| Grouping and hierarchy entities | Add an explicit document entity for organizing objects; evaluate groups, collections, or folders, including nesting, selection, and shared transform semantics. |
| Multiple authored scenes | **Draft; implementation deferred.** Independent N3 scenes in one document/editor. Revisit [RFC 0002](rfcs/0002-authored-scenes.md), starting with a small native-scene proof of switching, history/recovery, and persistence before broader import work. |
| Executable guide authoring | lgtmd has moved to its [own repository](https://github.com/lgtmd/lgtmd); N3 consumes an exact Git revision. Migrate the remaining 26 N3 templates through the existing adapter when scheduled, and switch to crates.io after an explicitly authorized SDK release. See [the boundary](docs/architecture/executable-documents.md) and historical [RFC 0004](rfcs/0004-lgtmd-web-incubation.md). |
| Executable guide authoring | lgtmd has moved to its [own repository](https://github.com/lgtmd/lgtmd); N3 pins lgtmd 0.3.0 from crates.io. Migrate the remaining 26 N3 templates through the existing adapter when scheduled. See [the boundary](docs/architecture/executable-documents.md) and historical [RFC 0004](rfcs/0004-lgtmd-web-incubation.md). |
| 3D format I/O | Build on read-only glTF/GLB viewing: scene export/authoring, OBJ export, compression and advanced extensions; evaluate OpenUSD composition/schema support. See the [viewer milestone](docs/milestones/modern-scene-viewer.md). |
| Materials and PBR | Extend imported PBR viewing into editable material assignment; HDR environment import, shadows, advanced materials and color management. See the [viewer milestone](docs/milestones/modern-scene-viewer.md). |
| Node Canvas UI Kit | Establish reusable UI primitives for node blocks, ports, connections, selection, dragging, pan, and zoom. Validate interactions in isolated workbench examples so future editors can adopt them confidently when a concrete consumer exists. Scope this as UI foundation work; shader/modifier semantics and evaluation remain separate. |
Expand Down
50 changes: 46 additions & 4 deletions docs/architecture/documentation-pipeline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,19 +67,61 @@ must not link back to them. Link validation rejects those outbound references.
browser. It uses Python 3's standard library and a vendored Docsify 5 runtime;
all scripts and styles load locally. The generated guide index supplies the
sidebar, and pages use their existing Markdown links and WebP assets, including
animations. There is no second content tree or separate site build.
animations. This preview needs no separate content tree or site build.

This presentation layer does not execute scenarios, regenerate artifacts, or
approve a baseline. After `just docs update`, refresh the browser to see the
changed output. `just docs check` still performs the strict replay described
below. `just docs-preview-test`, included in `just verify`, checks the server
routes and local browser assets independently of the GPU pipeline.

Keep this preview disposable. The pipeline continues to produce ordinary
Markdown and media that a future website can consume; the local viewer does not
commit N3 to a production documentation framework. See
Keep this preview disposable. The canonical pipeline continues to produce
ordinary Markdown and media independently of the local lgtmd site export. See
[development](../development.md#documentation-is-executable) for server options.

## Local lgtmd site

The native lgtmd CLI provides a second local reading and review surface. At the
current SDK pin, full N3 media requires the unreleased SDK CLI large-media host
fix described in [setup](../development.md#local-lgtmd-site); the unmodified
pinned CLI cannot carry the complete collection.
From the repository root, `lgtmd dev` reads
[lgtmd.config.json](../../lgtmd.config.json), starts a loopback server, and invokes
`just docs flow`. A repository-local installation can be invoked as
`.cache/tools/lgtmd/bin/lgtmd dev`; see [setup](../development.md#local-lgtmd-site).
The flow requires the CLI's unique `LGTMD_OUTPUT` and `LGTMD_RUN_ID` environment
before starting capture.

The [artifact pipeline](../../src/documentation/artifacts.rs) uses the same
`generate_outputs` replay to build the canonical Reader tree and retain completed
SDK documents. The [site bridge](../../src/documentation/site.rs) reuses
Rust-authored documents and adapts retained templates through typed `Guide`
bindings and captured-resource handles. Before exact Reader fragment comparison,
`site::legacy_fragment` translates the SDK's known additional HTML entity
spellings for Markdown punctuation inside generated `code` and `kbd` labels
back to N3's existing label spelling. Text outside those labels stays untouched;
narrative text, whitespace, resource paths, and media still compare exactly.
Canonical guide baseline checks remain unchanged. All media comes from those
same sessions with unchanged bytes; there is no site-specific capture or second
source of prose.

The site uses full SDK export titles and explicit section anchors, with the
canonical `README.md` index represented by `overview.md`. Site preparation makes
those presentation changes on copied documents, leaving the canonical fragments
and guide manifest untouched. After replay resources are released,
`handoff::complete_run` writes the completed documents for the CLI. The CLI
requires a matching run receipt and successful process exit, compiles both
audiences, and admits the completed candidate. Contributor notes remain outside
the Reader projection.

Configured candidates, local site snapshots, and static output live in ignored
`.cache/lgtmd`, `.cache/lgtmd-snapshots`, and `build/docs-site`. A first dev session
reports the absence of a recorded Git site baseline. Dev does not accept a
snapshot, regenerate `docs/guide`, or publish. `--watch` reruns the configured
flow on input changes; `--reuse` serves its last completed candidate without
replay. N3's `just docs`, `just docs check`, and `just docs update` keep their
existing preview, strict verification, and intentional baseline-update roles.

## One replay and rendering path

`Session` delivers pointer and keyboard events to the real `WorkspaceUi` and its
Expand Down
97 changes: 74 additions & 23 deletions docs/architecture/executable-documents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,15 @@

The [lgtmd SDK](https://github.com/lgtmd/lgtmd) separates document
composition and artifact publication from the application being documented.
N3 remains one application crate and consumes lgtmd from an exact Git revision.
The SDK, its Node bridge, and portable Rust/React examples are maintained in the
N3 remains one application crate and pins lgtmd 0.3.0 from crates.io.
The SDK, its native CLI and Node bridge, and portable Rust/React examples are maintained in the
lgtmd repository. N3 owns its application adapter, replay, renderer, scenarios,
and guide artifacts here. Neither SDK use nor its examples requires N3's renderer,
UI stack, website, or agent skill.

The SDK remains experimental and unpublished. Moving its source establishes
independent repository ownership; it does not establish a public release or a
stable API. A future registry dependency can replace the Git pin after the
package passes its release gates.
The SDK remains experimental. N3 pins the exact crates.io release `0.3.0`.
Publication does not establish a stable API or N3 compatibility; dependency
updates still require native verification and exact guide checks.

## The shared contract

Expand All @@ -36,12 +35,13 @@ reference. N3's [documentation pipeline](documentation-pipeline.md) owns product
replay, timing, captures, and renderer-specific evidence. This document records
the boundary between them.

The current public exporter targets Markdown. Artifact producers are generic,
but there is no public structured document-view API for a different publisher
yet. Prove that interface with an actual alternate exporter before exposing it;
it must preserve audience filtering, typed references, observations, and resource
ownership together. The private document model is the extension boundary, without
a plugin registry or a promise of arbitrary presentation support today.
N3's canonical guide and paired Markdown review trees use the SDK's fragment
exporter and retain their existing format. Its local docs-site flow also uses
`handoff::complete_run` to pass completed documents to the native lgtmd CLI. That
CLI owns `site::compile` for structured, audience-filtered site content with exact
resource sidecars, and `review::compare` for page and resource pairing between
retained site bundles. Both presentations use the same N3 replay, narrative
sources, and captured media.

## Internal Rust ownership

Expand All @@ -57,8 +57,9 @@ Markdown exporter.
inventory. It preserves unknown-field compatibility and distinguishes explicit
JSON null observations from omitted private payloads. `store` applies that receipt
policy to `lifecycle` filesystem operations; `runner` coordinates project-owned
generation and publication. These boundaries add no public serialized document
model or host executor.
generation and publication. The authored document model remains private. Public
`site` projections serialize audience-filtered content; application execution
remains consumer-owned.

## Project-owned configuration

Expand Down Expand Up @@ -96,13 +97,15 @@ does not add a configuration file format, plugin loader, or repository abstracti

## N3 ownership

| Layer | Responsibility |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `Session` and the production application | Real input routing, fixture setup, witnessed controls, behavioral assertions, explicit time, rendering, and capture. |
| [Guide adapter](../../src/documentation/guide.rs) | Convert witnessed controls, canonical key labels, and captured N3 media into typed SDK bindings and resources. |
| SDK `Doc` and `Document` | Compose narrative, retain immutable evidence and contributor notes, validate handles, and render the selected audience. |
| [N3 artifact pipeline](../../src/documentation/artifacts.rs) | Select the registered narrative, assemble the existing guide tree and text manifest, validate guide-only links, and enforce renderer policy. |
| SDK `lifecycle` | Validate output paths and inventories, compare complete trees, stage updates, publish, and retain recovery material on interruption. |
| Layer | Responsibility |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Session` and the production application | Real input routing, fixture setup, witnessed controls, behavioral assertions, explicit time, rendering, and capture. |
| [Guide adapter](../../src/documentation/guide.rs) | Convert witnessed controls, canonical key labels, and captured N3 media into typed SDK bindings and resources. |
| SDK `Doc` and `Document` | Compose narrative, retain immutable evidence and contributor notes, validate handles, and render the selected audience. |
| [N3 artifact pipeline](../../src/documentation/artifacts.rs) | Select the registered narrative, assemble the existing guide tree and text manifest, validate guide-only links, and enforce renderer policy. |
| [N3 site bridge](../../src/documentation/site.rs) | Adapt the same completed narratives to full SDK documents, check fragment parity, and prepare site page titles, index links, and section anchors. |
| Native lgtmd CLI | Execute the configured N3 flow, validate its completed handoff and successful exit, compile site projections, retain candidates, and serve local review. |
| SDK `lifecycle` | Validate output paths and inventories, compare complete trees, stage updates, publish, and retain recovery material on interruption. |

`Guide::control` requires that the same replay witnessed the control. Shortcut
labels come from the production binding catalog; requesting a label does not
Expand Down Expand Up @@ -155,6 +158,53 @@ validates links across the complete guide. Normal SDK `render_many` exports keep
their own complete-bundle validation. The existing N3 guide baseline, media, and
`manifest.txt` format are retained rather than converted to SDK manifest JSON.

## Local site handoff

`lgtmd dev` uses the root [configuration](../../lgtmd.config.json) to invoke
`just docs flow`. The guarded flow requires the per-run `LGTMD_OUTPUT` and
`LGTMD_RUN_ID` environment supplied by the CLI before it starts capture. The
ordinary `generate_outputs` path replays every feature once, validates the
canonical Reader tree, and retains completed documents from those same sessions.
After generation releases its renderer and session resources, N3 prepares the
site documents and calls `handoff::complete_run`. The CLI also requires successful
process exit before admitting a candidate; writing a receipt cannot conceal a
later failure.

Rust-authored guides reuse their completed SDK documents. Retained templates
adapt their registered source through `Guide`'s typed control, shortcut, key,
modifier, and captured-resource handles. The bridge compares each document's
Reader fragment, including N3's generated preamble, with the ordinary guide
page before site preparation. The SDK additionally HTML-escapes Markdown
punctuation in typed labels, including backslashes. `site::legacy_fragment`
translates only those known stronger entity spellings inside generated
`code` and `kbd` labels back to N3's existing spelling, then compares the result
exactly. Narrative text, whitespace, resource paths, and media retain exact
comparison, and canonical guide baseline checks remain unchanged. The bridge
does not ingest generated pages as a new narrative source or recapture media.

Full SDK export supplies the site page title and explicit block anchors. N3's
site preparation removes the duplicate authored title, creates explicit section
anchors, and maps canonical `README.md` index links to the `overview.md` site
page. These are site presentation changes to copies of the completed documents;
the canonical fragments, media paths, media bytes, and text manifest remain
unchanged. Site Markdown and structured bundles therefore have their own export
format, while the explanation and evidence come from the same registered source.

The native CLI is installed separately from N3's crates.io SDK dependency, under
ignored `.cache/tools/lgtmd`. The unmodified 0.3.0 CLI's encoded JSON limits
reject N3's complete media collection. Local integration therefore uses an isolated SDK build with an
unreleased large-media handoff and retained-candidate host fix, verified
separately from N3. That fix needs to land upstream; N3's pinned application
dependency, canonical captures, and media resolution remain unchanged, and the
SDK host fix stays outside N3's tracked source. The root
configuration keeps retained candidates in `.cache/lgtmd`, local site snapshots
in `.cache/lgtmd-snapshots`, and static site output in `build/docs-site`. These
outputs remain ignored local review material. Starting dev does not accept a
site snapshot or update the canonical guide; an unavailable recorded Git site
baseline is reported explicitly. `just docs` retains its existing Docsify
preview, and `just docs check/update` retain N3's verification and intentional
guide-update roles. See [local setup](../development.md#local-lgtmd-site).

## Shared publication with explicit ownership

N3 and the portable consumers share the SDK's `lifecycle` implementation while
Expand Down Expand Up @@ -226,7 +276,7 @@ still need human review.
## Node and web integration

[packages/lgtmd](https://github.com/lgtmd/lgtmd/blob/main/packages/lgtmd/README.md) authors documents in Node 24 ESM;
[crates/lgtmd-node](https://github.com/lgtmd/lgtmd/blob/main/crates/lgtmd-node/Cargo.toml) is its coarse native bridge.
[crates/lgtmd-cli](https://github.com/lgtmd/lgtmd/blob/main/crates/lgtmd-cli/Cargo.toml) owns the shared native command and its internal coarse bridge.
One serialized request per compile/publication carries schema-v1 frozen input to
the same Rust validation, Markdown exporters, runner and owned store. The wire
contains complete ordered content and resource snapshots, never process-local
Expand Down Expand Up @@ -254,7 +304,8 @@ filesystem store returned an unsupported-platform error. The selected native
route retains the existing strict filesystem contract. It requires platform
binaries in npm tarballs; installation performs no Rust build. Node 24 ESM on
macOS arm64 is the executed local scope. Linux x64 has CI wiring, not a completed
runtime claim. A full viewer and browser-hosted SDK are deferred.
runtime claim. A browser-hosted SDK remains deferred; the native CLI embeds its
local docs-site viewer.

The SDK repository owns explicit browser setup and its Node/Chromium verification
workflow. It checks the native bridge, authoring and failure semantics, real
Expand Down
Loading
Loading