DSL extensibility generator · foundation, map and generation · the two examples are real code
Many languages, layered into one.
A base DSL gives you a grammar and tools. An extension layer adds a vocabulary. Your product then needs its own words: its node types, its fields, its commands. Plyglot is the tool that scaffolds that last layer as one more ply, so your dialect stays a valid document of the layer below and every tool under it keeps working. Then it shows which ply each feature comes from.
Watch a dialect at work Built in three layers Whose feature is it? What the generator emits
- Layers
- 3
- Features mapped, with provenance
- 33
- Worked examples, from code on disk
- 2
- Carrier formats
- 4 · JSON, YAML, TOML, HCL
How people on different layers understand each other, in 27 seconds
The film needs JavaScript, which has not run. Its beats follow.
- Three languages stack up:
.plyx, the engine scene, generic and powerful with the fewest opinions;.thrd, the whiteboard vocabulary;.tpd, the most opinionated. - Three different people enter at three different layers: an engine builder at
.plyx, a whiteboard app maker at.thrd, a debate app maker at.tpd. - A file written at the top is passed down. Each of them can read it, because every layer is a valid document of the layer below.
- More people branch their own dialects off each layer, and the picture widens into an ecosystem. Nobody needed an API from anybody else.
Download the film · mp4, 1280 × 720, 27 s, 612 kB · rendered from this same animation by tools/film-export.ts
The idea: three layers, each a valid document of the one below
Extending a language safely is mostly agreeing where your words go. The same three roles show up in a diagram format and in a task-list format.
Three layers on one loom
- The base DSL is the warp: someone else's grammar, validator and tools.
- An extension layer weaves a shared vocabulary across it, by contract.
- Your dialect is the top weft: your own types and fields, under your namespace.
- No layer cuts a thread below it. Lower tools still read the file.
-
Base DSL
A grammar, a validator and tools you do not own. It decides what a document is and which parts it will carry without understanding.
.plyx engine scene · yap@1
-
Extension layer
A vocabulary added through the base's own seam: named contracts, registered types, declared in the document so a reader knows what it needs.
.thrd: thrd:whiteboard, thrd:thread
-
Local dialect
One product's words and their implementation details: field shapes, defaults, limits, commands, how the host draws and runs them.
.tpd pills · a program's task members
Three rules both examples already keep
- Everything of yours is namespaced.
threadpilled:app/pill,threadpilled:pill/kind.set@1,#@threadpilled:accounts. Two dialects on one base never collide. - A reader that does not know you keeps your data. thrd.it keeps an unknown host namespace through its own edits. Yapture keeps unknown
@taskmembers as opaque JSON. - The base's validator still passes. A pill is stored as a card the engine can draw. A roadmap item is a task Yapture can lint. The dialect's own checks run after, not instead.
Scenes: script, extension and state, moving together
Three short films. Each shows a script on the left, what a host makes of it, and the state it leaves behind, one beat at a time. Watch where a layer's line lands, what it changes, and what the layer below still understands.
The films need JavaScript, which has not run. Their beats, in words:
- A card becomes a pill. An engine scene gains thrd.it's cards and a thread; ThreadPilled registers its pill type, changes a kind with one command and labels the thread with a relation; thrd.it reopens the file and keeps what it does not know.
- A list that runs. A Yapture list gains a program's members; the dialect's check catches a ticked box that Yapture accepts; the host works out what can start and changes state through the dialect. Typed task checks and runner stubs are generated.
- Whose feature is it? The tool snapshots each layer's registries and finds that shapes are a parent feature two layers overload.
Use Play, Back and Next, or the arrow keys. The films stop when they leave the screen and do not start by themselves when your system asks for reduced motion.
Worked example A: .plyx → .thrd → .tpd
PlyLoom's engine draws a scene. thrd.it adds a whiteboard vocabulary to it. ThreadPilled adds pills, relations and host data. One document, growing a layer at a time:
The layered document needs JavaScript, which has not run. The three layers are shown as code below.
Assembled for this page from the shapes in thrdit/boards/*.thrd, thrdit/packages/core and threadpilled-app/src/pills. It is the JSON form thrd.it saves; it is not a file copied from disk. A .tpd file holds exactly this text today: ThreadPilled registers .tpd as an export and import format, and .tpd as its own language is planned.
-
Base: the engine scene and its container specified
.plyxis PlyLoom's container: artifacts, each in a registered language, each lowering to onethrd: 1envelope the engine validates and draws.- A closed container:
ply,requires,meta,artifacts. definePlyregisters a language withvalidate,lower,lift.- Third-party languages use their own namespace, e.g.
acme:poster@1.
plyloom/rnd/specs/68-bolt.md, B2 and B3. Draft of 2026-11-10: a prototype runs on the PlyLoom site, nothing in the engine.
launch.plyx · text form (SPEC-68 B2)ply 1 requires [loom:thrd@1, loom:meme@1] meta { title: "Launch" } artifacts { board { type: "whiteboard" dsl: "loom:thrd@1" body { requires { "thrd:scene": 1, "thrd:whiteboard": 1 } scene { … } } } card { type: "meme" schema: "loom:meme@1" body { layers [ … ] } } gpu { type: "view" of: "board" render { device: "webgpu" clear: "#101418" } } }PlyLanguage · the registration a language supplies (SPEC-68 B3)interface PlyLanguage { id: ContractId; // "loom:thrd@1", "loom:meme@1" kind: "dsl" | "schema"; // dsl: has its own text form; schema: plain .plyx configuration ext?: string; // kind "dsl" only: its standalone file extension, ".thrd" artifact: string; // artifact type it produces validate(body, path): Problem[]; lower(body, ctx: { title: string }): JsonValue; // → a valid thrd envelope; pure, deterministic lift(doc: JsonValue): Body; // lift(lower(b)) = b for every valid b } definePly(lang): PlyLanguage // throws on a duplicate id (no silent replacement) - A closed container:
-
Extension layer: thrd.it's vocabulary and its host seams built
.thrdadds cards, shapes and threads as contracts inrequires. For the layer above, the SDK opens five seams. These are what a dialect is made of.- Host identity and host commands: your namespace, your registered appliers, one commit each.
- Host data: one slot per node under
meta.host[namespace]. registerNodeType: your kind of node, drawn over a carrier the engine knows.registerShapeandregisterTool: your outlines and toolbar tools.
thrdit/packages/core/README.md and packages/interaction/README.md, @thrdit/core 0.17.0.
the five seams · from the @thrdit/core and @thrdit/interaction READMEs// 1. Host commands: start from appRegistry(identity), register, and pass it to the Board. const registry = appRegistry(identity); // identity.commandNamespace: "myapp:app" registry.register("myapp:pill/categorise@1", (doc, args) => { /* pure: change doc, return it */ return doc; }); // 2. Host data on a node (0.7.0): stored under meta.host[<namespace>][<node id>] board.setHostData(id, { kind: "claim", source: { title: "Reading study" } }); // one commit board.hostData(id); // { kind: "claim", … } or undefined hostDataIn(document, "threadpilled:app"); // every node's data in a namespace, without a Board // 3. Host node types (0.8.0) registerNodeType({ type: "threadpilled:app/pill", label: "Pill", size: [220, 96], // carrier: "card" by default, or a shape render: (c) => `<text x="10" y="16">${escapeMarkup(c.data?.kind ?? "note")}</text>`, // SVG, in the node's own box inspect: [{ id: "kind", label: "Kind", kind: "select", options, get: (c) => c.data?.kind ?? "claim", set: (c, v) => ({ ...c.data, kind: v }) }], }); // 4. Host shapes (0.15.0) registerShape({ id: "myapp:kit/parallelogram", label: "Parallelogram", icon: "M7 5h14l-4 14H3z", size: [180, 90], path: (w, h) => `M ${w * 0.2} 0 L ${w} 0 L ${w * 0.8} ${h} L 0 ${h} Z`, // the outline for a box w by h, closed }); // 5. Tools (@thrdit/interaction) mountWhiteboard(host, { tools: [...TOOLS, stamp] }); // or registerTool(stamp) before mounting -
Local dialect: ThreadPilled's pills, relations and host data built .tpd as a language: planned
ThreadPilled uses those seams and nothing else. The implementation details are its own: four pill kinds, a tolerant reader, limits on every field, three relations, five versioned commands.
- A pill is the type
threadpilled:app/pillon a card carrier, with its fields in host data. - Reading never fails: missing or malformed takes a default, an unknown kind is kept.
- A relation is a thread's label:
supports,disputes,cites. .tpdis a registered export and import format whose text is the map's.thrddocument. Registering it as a language that extends.thrd, with its own grammar and validation, is open work (TP-04.7, ENG-03.7).
threadpilled-app/src/canvas/identity.ts, src/canvas/tpd.ts, src/pills/pill.ts, src/pills/commands.ts (excerpts); docs/spec/TP-04, ENG-03.
src/canvas/identity.tsimport { appRegistry, hostIdentity, type CommandRegistry, type HostIdentity } from "@thrdit/core"; import { registerPillCommands } from "../pills/commands.ts"; export const THREADPILLED: HostIdentity = hostIdentity({ app: "threadpilled", systemActor: "app:threadpilled", historyKeyPrefix: "threadpilled:history", commandNamespace: "threadpilled:app", }); /** The command registry a ThreadPilled board runs: the SDK's vocabulary under both namespaces, and ThreadPilled's own commands (TP-04.3). */ export function threadpilledRegistry(): CommandRegistry { const registry = appRegistry(THREADPILLED); registerPillCommands(registry); return registry; }src/pills/pill.ts · the type, its data and its reader (excerpt)export const PILL_TYPE = "threadpilled:app/pill"; export const PILL_SIZE: readonly [number, number] = [240, 112]; /** Where evidence or a source comes from. Every field is optional. */ export interface PillSource { url?: string; title?: string; author?: string; date?: string; quote?: string; capturedAt?: string } export interface Pill { kind: string; source?: PillSource; tags: string[]; archived: boolean; /** The author's own, 0 to 1. */ confidence?: number; } /** A pill read from a node's host data. Anything missing or malformed takes its default; an unknown kind is kept. */ export function readPill(data: JsonValue | undefined): Pill { const d = isObj(data) ? data : {}; const kind = clean(d.kind, 40) || DEFAULT_KIND; const source: PillSource = {}; if (isObj(d.source)) for (const key of SOURCE_FIELDS) { const v = clean(d.source[key], key === "quote" ? 600 : 300); if (v) source[key] = v; } const confidence = typeof d.confidence === "number" && d.confidence >= 0 && d.confidence <= 1 ? d.confidence : undefined; return { kind, ...(Object.keys(source).length ? { source } : {}), tags: Array.isArray(d.tags) ? normalizeTags(d.tags) : [], archived: d.archived === true, ...(confidence !== undefined ? { confidence } : {}), }; }src/pills/commands.ts · commands and relations (excerpt)export const PILL_COMMANDS = { kind: "threadpilled:pill/kind.set@1", source: "threadpilled:pill/source.set@1", tags: "threadpilled:pill/tags.set@1", archive: "threadpilled:pill/archive.set@1", relation: "threadpilled:thread/relation.set@1", } as const; /** The relations a thread may carry (D-16). Which kinds each may join arrives with TP-04.2. */ export const RELATIONS = ["supports", "disputes", "cites"] as const; registry.register(PILL_COMMANDS.kind, (doc, args) => changePill(doc, PILL_COMMANDS.kind, args, (_now, a) => { if (typeof a.kind !== "string" || !/^[a-z][a-z0-9-]{0,39}$/.test(a.kind)) throw new Error(`${PILL_COMMANDS.kind}: kind must be a lower-case name`); return { kind: a.kind }; })); registry.register(PILL_COMMANDS.relation, (doc, args) => { const cmd = PILL_COMMANDS.relation; if (!isObj(doc) || !isObj(args) || typeof args.thread !== "string") throw new Error(`${cmd}: args must name a thread`); if (!isRelation(args.relation)) throw new Error(`${cmd}: relation must be one of ${RELATIONS.join(", ")}`); const nodes = isObj(doc.scene) && isObj(doc.scene.nodes) ? doc.scene.nodes : {}; const thread = own(nodes, args.thread) ? nodes[args.thread] : undefined; if (!isObj(thread) || thread.type !== "thrd:thread/thread") throw new Error(`${cmd}: ${args.thread} is not a thread`); thread.label = { ...(isObj(thread.label) ? thread.label : {}), text: args.relation }; return doc; }); - A pill is the type
Worked example B: your own language over Yapture's .yap
Yapture's list format is small on purpose. It has one seam, and a real program already uses it: ThreadPilled's roadmap is a dialect of yap@1. Plyglot generates the typed-task declarations and runner stubs in the third step.
The layered document needs JavaScript, which has not run. The layers are shown as code below.
An example list in the acme namespace, written for this page. Steps one and two follow ThreadPilled's real lists; step three shows Plyglot’s generated typed-task runner stub.
-
Base: the
yap@1grammar builtA version line, one
@list, then tasks and actions. Every record is one physical line. The JSON on a record must have a non-emptyid; its other members are opaque to Yapture.- That opacity is the seam: your members ride in the
@taskJSON. - Badges such as
#@track:areaand#!p0are lexical. The text keeps their spelling. requiredExtensionsmust be absent or empty, so ayap@1file cannot declare that it needs a dialect. The dialect is the host's knowledge.
threadpilled-app/roadmap/vendor/yap/grammar.ebnf and LINT-CONTRACT.md (the pinned @yapture/yap-portable). Its source is Yapture's
libsrepository (~/Code/github/yapture/libs), which also holds Yapture Script,@yapture/script-dsl, where#^namemeans a goal rather than ThreadPilled's phase.grammar.ebnf · yap@1 (excerpt)document = version, EOL, { trivia, EOL }, list, { EOL, (trivia | task | action) }, [ EOL ]; version = "@yap 1"; list = "@list ", jsonObject; task = "- [", (" " | "x"), "] ", text, EOL, " @task ", jsonObject, { EOL, " | ", text }; action = "@action ", jsonObject; (* jsonObject: strict JSON with unique object keys, nonempty string id; requiredExtensions absent or empty array. Other members are opaque JSON. *) - That opacity is the seam: your members ride in the
-
Local dialect: ThreadPilled's roadmap members, their checks and their runner built
The program defines
status,spec,phase,repo,gaps,dependsOn,decisionandevidence. Its scripts load lists through Yapture'sparseandlintfirst, then apply the dialect's own rules.- Validation: statuses and phases from a closed set, the checkbox agreeing with
status, dependencies that exist, no cycles. - How the host runs it:
next.tscomputes what can start,set.tschanges one item,build.tswrites the page. - Yapture's own CLI still lints and formats the same files.
threadpilled-app/roadmap/lists/threadpilled.yap, roadmap/scripts/lib.ts, check.ts (excerpts); docs/spec/PRG-01-tracking.md.
roadmap/lists/threadpilled.yap · two real items@yap 1 @list {"id":"threadpilled","label":"ThreadPilled","track":"threadpilled"} - [ ] Profile per issuer and subject; ThreadPilled account deletion; no credential columns #@threadpilled:accounts #!p1 #^p1 @task {"id":"TP-01.3","spec":"TP-01","status":"todo","phase":"P1","repo":"threadpilled-api","gaps":["a1"],"dependsOn":["TP-01.2"]} - [ ] App: sign in through /auth/sign-in, account menu and signed-in state #@threadpilled:accounts #!p0 #^p1 @task {"id":"TP-01.5","spec":"TP-01","status":"todo","phase":"P1","repo":"threadpilled-app","gaps":["a1"],"dependsOn":["TP-01.2","TP-01.4"]}roadmap/scripts/lib.ts · base first, then the dialect's members (excerpt)import { lint, parse } from "../vendor/yap/sdk.mjs"; export const STATUSES = ["todo", "doing", "blocked", "done", "deferred"] as const; export const PHASES = ["P0", "P1", "P2", "P3", "P4", "P5", "Later"] as const; const parsed = parse(text); for (const d of [...parsed.diagnostics, ...lint(text)]) findings.push({ where: file, message: `${d.code ?? "YAP"}: ${d.message ?? JSON.stringify(d)}` }); if (!parsed.model) continue; for (const task of parsed.model.tasks) { const [first = "", ...rest] = task.text.split("\n"); const m = task.metadata; const workspace = /#@([A-Za-z0-9_.-]+):([A-Za-z0-9_.-]+)/.exec(first); const pri = /(?:^|\s)#!p(\d)/.exec(first); items.push({ id: String(m.id), completed: task.completed, status: String(m.status ?? "") as Status, spec: String(m.spec ?? ""), phase: String(m.phase ?? ""), repo: String(m.repo ?? ""), gaps: Array.isArray(m.gaps) ? m.gaps.map(String) : [], dependsOn: Array.isArray(m.dependsOn) ? m.dependsOn.map(String) : [], priority: pri ? Number(pri[1]) : 3, area: workspace?.[2] ?? "", track: workspace?.[1] ?? track, // … }); }roadmap/scripts/check.ts and lib.ts · the dialect's validation and its runner (excerpt)// 3. Each item is well formed. for (const item of items) { const at = `${item.file} ${item.id}`; if (!STATUSES.includes(item.status)) add(at, `status "${item.status}" is not one of ${STATUSES.join(", ")}`); if (item.completed !== (item.status === "done")) add(at, `checkbox is ${item.completed ? "[x]" : "[ ]"} but status is ${item.status}`); if (!specIds.has(item.spec)) add(at, `spec ${item.spec || "(none)"} has no file in docs/spec`); for (const dep of item.dependsOn) { const target = byId.get(dep); if (!target) add(at, `depends on ${dep}, which does not exist`); else if (item.status === "done" && target.status !== "done") add(at, `is done but depends on ${dep}, which is ${target.status}`); } } /** Items that can start now: todo, every dependency done, decision (if any) answered. */ export function ready(items: Item[]): Item[] { const byId = new Map(items.map((i) => [i.id, i])); return items .filter((i) => !i.isDecision && i.status === "todo") .filter((i) => i.dependsOn.every((d) => byId.get(d)?.status === "done")) .filter((i) => !i.decision || byId.get(i.decision)?.status === "done") .sort(order); }running it · threadpilled-app/roadmap/README.mdbun roadmap/scripts/next.ts # what can start now, and the decisions holding work bun roadmap/scripts/set.ts TP-01.1 doing # change one item; rebuilds and checks bun roadmap/scripts/check.ts # lint lists, ids, dependencies, gap coverage, vendored hashes bun roadmap/vendor/yap/cli.mjs lint roadmap/lists/threadpilled.yap # Yapture's own tool, same file - Validation: statuses and phases from a closed set, the checkbox agreeing with
-
Typed tasks with a runner generated
Members are enough for status tracking. A language of your own wants task types: an approval, a deploy gate, a data check. Plyglot generates their checks and runner stubs without changing the grammar.
- A
kindmember names a type in your namespace, versioned like a command:acme:task/approval@1. - Each type brings declared checks and a write-once
runstub for the host to implement. - The base grammar is checked first. A task with no
kindstays a plain task. An unknown kind is reported and never run.
examples/yap-tasks/dialect.ts and src/emitters/yap.ts. The example below is generated by the real emitter. Validation uses the pinned Yapture SDK; the host implements each task body.
acme.tasks.ts · generated stub// Written once by plyglot. Task runners belong to the dialect author. import { runYapTask, type YapRunner, type YapCheckContext } from "plyglot/yap"; import { CONFIG } from "./acme.schema.ts"; export interface Host { requestApproval?(id: string, approvers: readonly string[]): unknown | Promise<unknown> } export const TASK_KINDS: Record<string, YapRunner<Host>> = { "acme:task/approval@1": async (_task, _host) => { // TODO: implement acme:task/approval@1. Only validated known kinds reach this body. throw new Error("TODO: implement acme:task/approval@1"); }, }; export function run(source: string, id: string, host: Host, context?: YapCheckContext) { return runYapTask(CONFIG, source, id, TASK_KINDS, host, context); } - A
Feature map: where each feature comes from
Once a language has layers, the first question about any feature is whose it is. Pick a layer to stand on, then a feature: the map says whether it is a parent's, a sibling's, this layer's own or a child's, what it does, and, when a layer overloads it, what differs.
The feature map needs JavaScript, which has not run.
Try: view from ThreadPilled and pick Shapes (a parent feature it overloads), Pills (its own addition), or shape/triangle (withheld). Every row names the pinned file it was read from.
What the generator produces thrd.it implemented
Both examples were written by hand, and both repeat the same four pieces. Plyglot's job is to emit those pieces from one description of your dialect, and to show the result as a map of whose feature is whose.
- 1 · Namespace and schema
acme.schema.ts
Type ids, command ids, field shapes and limits, in one namespace. - 2 · Validators
acme.validate.ts
A reader that never throws and a writer that keeps fields it does not know. - 3 · Registration stubs
acme.register.ts
The calls into the base's seams, with the render and run bodies left for you. - 4 · Conformance test
acme.conformance.test.ts
Proof that the base still accepts the document and a stranger keeps your data. - 5 · Feature map
feature-map.json
Every feature with its owner, its relation to your layer and what an overload changes. Read from the registries.
The feature map, derived instead of drawn built for the diagram chain
The map above is the fifth thing the tool is meant to produce, and the only one that reads rather than writes. Each base adapter lists what a layer registers, the namespace of every id says which layer owns it, and an id that two layers define differently is an overload. Nobody draws it. The sketch below describes the implemented registry adapter.
// Interface sketch. The implemented worker loads one pinned layer per Bun process.
import { exportFormats, importFormats, nodeTypes, shapeCatalog, TOOLS } from "@thrdit/core";
export function snapshot(layer: LayerRef, registry: CommandRegistry, tools = TOOLS): Snapshot {
return {
layer: layer.id, parent: layer.parent,
features: [
...nodeTypes().map((t) => feature("node type", t.type, t)), // "threadpilled:app/pill"
...shapeCatalog().map((s) => feature("shape", s.id, s)), // the engine's eight, then host shapes
...exportFormats().map((f) => feature("format", f.id, f)), // "tpd"
...importFormats().map((f) => feature("format", f.id, f)),
...tools.map((t) => feature("tool", t.id, t)), // the list the host mounts
...commandIds(registry).map((id) => feature("command", id)), // implemented: wrap register until upstream ids() exists
],
};
}
// Run once per layer, bottom up. Then, for every feature id:
// only in the child's snapshot → added by the child
// in the parent's, unchanged → inherited
// in both, with a different definition → overloaded: the diff is the two definitions, field by field
// explicitly excluded by the child → withheld (ThreadPilled's toolbar and five of the eight shapes)
// owner = first defining layer → engine owns thrd:ink/shape; descendants overload it
export function featureMap(snapshots: Snapshot[]): FeatureMap { /* … */ }
bun src/cli/main.ts map --from threadpilled # writes JSON, data JS and self-contained HTML
bun src/cli/main.ts map --feature thrd:ink/shape # one feature: owner, relation, and the diff per layer
For yap@1, the adapter reads the pinned grammar and lint contract, then each dialect’s declared members and checks. Features that exist only in a spec (ThreadPilled's comments) would come from the spec's front matter and be marked planned.
The input
import { defineDialect } from "plyglot";
export default defineDialect({
"name": "acme-notes",
"base": "thrd",
"namespace": "acme:app",
"ext": ".acme",
"nodeTypes": {
"note": {
"carrier": "card",
"size": [
220,
96
],
"data": {
"kind": {
"enum": [
"idea",
"risk",
"decision"
],
"default": "idea",
"normalize": "space",
"max": 40
},
"owner": {
"type": "string",
"max": 80,
"optional": true,
"normalize": "space"
}
}
}
},
"commands": {
"note/kind.set@1": {
"args": {
"node": "node",
"kind": "data.kind"
}
}
}
});
bunx plyglot init --base thrd --namespace acme:app # writes plyglot.config.ts
bunx plyglot generate # writes code, fixtures, harness and JSON Schema
bunx plyglot check # checks drift and runs the harness
The output
// GENERATED by plyglot. Do not edit; regenerate from plyglot.config.ts.
export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
export const NAMESPACE = "acme:app";
export const DIALECT_CONFIG = {
"base": "thrd",
"commands": {
"note/kind.set@1": {
"args": {
"kind": "data.kind",
"node": "node"
}
}
},
"ext": ".acme",
"name": "acme-notes",
"namespace": "acme:app",
"nodeTypes": {
"note": {
"carrier": "card",
"data": {
"kind": {
"default": "idea",
"enum": [
"idea",
"risk",
"decision"
],
"max": 40,
"normalize": "space"
},
"owner": {
"max": 80,
"normalize": "space",
"optional": true,
"type": "string"
}
},
"size": [
220,
96
]
}
}
} as const;
export const COMMANDS = {
"note/kind.set@1": "acme:note/kind.set@1"
} as const;
export const NOTE_TYPE = "acme:app/note";
export const NOTE_SIZE: readonly [number, number] = [220,96];
export const NOTE_FIELDS = {
"kind": {
"default": "idea",
"enum": [
"idea",
"risk",
"decision"
],
"max": 40,
"normalize": "space"
},
"owner": {
"max": 80,
"normalize": "space",
"optional": true,
"type": "string"
}
};
export const NOTE_KIND_VALUES = ["idea","risk","decision"] as const;
export const DEFAULT_NOTE_KIND = "idea";
export interface Note {
"kind": string;
"owner"?: string;
}
// GENERATED by plyglot. Do not edit; regenerate from plyglot.config.ts.
import { readData, writeData, checkFieldArg } from "plyglot/thrd";
import type { FieldShape } from "plyglot";
import { NOTE_FIELDS, type Note, type Json } from "./acme.schema.ts";
export function readNote(data: unknown): Note { return readData(NOTE_FIELDS as Record<string, FieldShape>, data) as unknown as Note; }
export function noteData(value: Partial<Note>, base?: unknown): Json { return writeData(NOTE_FIELDS as Record<string, FieldShape>, value, base); }
export function checkNodeArg(value: unknown): string { return checkFieldArg({"type":"string"}, value, "acme:note/kind.set@1: node") as string; }
export function checkKindArg(value: unknown): string { return checkFieldArg({"enum":["idea","risk","decision"],"default":"idea","normalize":"space","max":40}, value, "acme:note/kind.set@1: kind") as string; }
export function checkNoteKindSet1Args(value: unknown): { "node": string; "kind": string } {
return checkFieldArg({"type":"object","fields":{"node":{"type":"string"},"kind":{"enum":["idea","risk","decision"],"default":"idea","normalize":"space","max":40}}}, value, "acme:note/kind.set@1") as { "node": string; "kind": string };
}
// Written once by plyglot. This file belongs to the dialect author.
import { appRegistry, escapeMarkup, hostIdentity, registerNodeType, type CommandRegistry } from "@thrdit/core";
import { conformanceRegistry } from "plyglot/thrd";
import { COMMANDS, NAMESPACE, NOTE_TYPE, NOTE_SIZE } from "./acme.schema.ts";
import { checkNoteKindSet1Args } from "./acme.validate.ts";
export const IDENTITY = hostIdentity({ app: "acme-notes", systemActor: "app:acme-notes", historyKeyPrefix: "acme-notes:history", commandNamespace: NAMESPACE });
export function registerTypes(): () => void {
const remove = [
registerNodeType({ type: NOTE_TYPE, label: "Note", carrier: "card", size: NOTE_SIZE,
// TODO: render SVG in the node's own box; escape all interpolated text.
render: (ctx) => `<text x="10" y="16">${escapeMarkup(ctx.text)}</text>`,
}),
];
return () => remove.reverse().forEach((dispose) => dispose());
}
export function createRegistry(): CommandRegistry {
const registry = conformanceRegistry(appRegistry(IDENTITY));
registry.register(COMMANDS["note/kind.set@1"], (_doc, args) => {
const checked = checkNoteKindSet1Args(args);
void checked;
// TODO: apply the command to doc. Pure appliers read and write only doc and recorded args.
throw new Error("TODO: implement acme:note/kind.set@1");
});
return registry;
}
// GENERATED by plyglot. Do not edit; regenerate from plyglot.config.ts.
import { test, expect } from "bun:test";
import { baseValidates, strangerRoundTrip, assertHostPreserved, verifyReplay, checkDocument, type CommandLog } from "plyglot/thrd";
import type { DialectConfig } from "plyglot";
import fixture from "./acme.fixture.json";
import { createRegistry, IDENTITY } from "./acme.register.ts";
import { NAMESPACE, NOTE_TYPE } from "./acme.schema.ts";
import config from "./corpus/acme.config.json";
import commandLog from "./acme.commands.json";
test("base validates dialect fixture", async () => { expect(await baseValidates(fixture)).toEqual([]); });
for (const edit of ["move-every-node", "duplicate-every-node", "undo-redo"] as const) test(`stranger preserves host data: ${edit}`, async () => { assertHostPreserved(fixture, await strangerRoundTrip(fixture, { edit }), [NAMESPACE, "thrd:node-type"]); });
test("commands replay twice and verify through the engine", async () => { await verifyReplay(fixture, commandLog as unknown as CommandLog, createRegistry()); });
test("dialect validates after its base", async () => { expect(await checkDocument(config as unknown as DialectConfig, fixture)).toEqual([]); });
test("type ids and host identity stay inside the namespace", () => {
for (const type of [NOTE_TYPE]) expect(type.startsWith(NAMESPACE + "/")).toBe(true);
expect(IDENTITY.commandNamespace).toBe(NAMESPACE);
});
With base: "yap", the generator emits a members schema, checks after parse and lint, task kinds with write-once run stubs, an export profile, fixtures and runnable law/conformance tests.
One dialect, editor tools and four formats
The same config supplies language tooling, JSON Schema and format conversion. Everything runs locally with pinned dependencies.
Language tooling JSON-carried thrd.it dialects
The language server provides base-first diagnostics, completion, provenance hover, definitions, formatting and semantic tokens that distinguish base, extension and dialect. YAML, TOML and HCL diagnostics point back into the carrier text. Capabilities can be disabled in tooling.lsp.
plyglot editor emits local Neovim, VS Code, Helix, Zed and Emacs packages. Neovim uses its JSON parser and the shared server. The standalone thrd text grammar and the Zed compiled extension remain verification gaps; their source is supplied, with no download or marketplace step.
bunx --no-install plyglot editor --target nvim
bunx --no-install plyglot lsp # stdio; started by the editor
JSON, YAML, TOML and HCL round-trip laws tested
Converters use one document model and Plyglot-owned printers. Unsupported values fail with their JSON pointers unless the config explicitly declares the loss. TOML cannot carry null. HCL supports data attributes, labelled blocks, objects, tuples and literals; expressions and interpolation are rejected at their source spans.
plyglot generate also emits dialect.schema.json. The real YAML language server is tested against that schema. Codec tests cover 1,000 seeded models per format for both acme-notes and ThreadPilled.
bunx --no-install plyglot convert map.tpd --to yaml --out map.tpd.yaml
bunx --no-install plyglot convert map.tpd.yaml --to tpd --out roundtrip.tpd
Built, specified, planned
Every claim on this page about another project was checked against that project's files on 15 November 2026. This is where each piece stands.
| Piece | Stands | Where it was read |
|---|---|---|
.thrd documents: scene, contracts in requires | built | thrd.it boards on diskthrdit/boards/*.thrd |
| thrd.it host seams: identity and commands, host data, node types, shapes, tools | built | @thrdit/core 0.17.0thrdit/packages/core/README.md, packages/interaction/README.md |
| ThreadPilled pills, pill commands, relations | built | Stored inside .thrdthreadpilled-app/src/pills/*, src/canvas/identity.ts |
yap@1 grammar, parse and lint | built | Vendored @yapture/yap-portablethreadpilled-app/roadmap/vendor/yap/ |
ThreadPilled's roadmap dialect over .yap | built | Lists and Bun scriptsthreadpilled-app/roadmap/lists, roadmap/scripts |
.plyx container and definePly | specified | SPEC-68, Draft; prototype on the PlyLoom site onlyplyloom/rnd/specs/68-bolt.md |
.tpd as an export and import format (its text is the .thrd document) | built | Registered through thrd.it's format registrythreadpilled-app/src/canvas/tpd.ts |
.tpd as a registered language with its own grammar | planned | TP-04.7 and ENG-03.7 are todo; language extends is not in SPEC-68threadpilled-app/docs/spec/TP-04, ENG-03 |
| ThreadPilled comments, profiles, follows, upvotes | planned | Specified; all eight TP-05 items are todothreadpilled-app/docs/spec/TP-05-social.md |
| Feature map on this page: relations, overload markers and diffs computed from a layer tree | built | Generated from pinned registries; shared with the CLIassets/feature-map.data.js; src/viewer |
| Hero film: a programmatic animation, drawn as a function of time | built | The six branch dialects it shows are illustrations, not productssites/plyglot/assets/film.js |
| Scenes on this page: three films of script, stage and state | built | Scripted by hand from the same sources; the third shows the planned toolsites/plyglot/assets/scenes.js |
Feature map derived automatically from the layers' registries (plyglot map) | generated | PlyLoom, thrd.it SDK, ThreadPilled; app lane catalogued only; Yapture grammar, Script and two roadmaps mappedsrc/adapters/thrd, src/core, src/cli; assets/feature-map.data.js |
Typed tasks (kind) and a runner over Yapture | generated | Typed checks and host-owned runner stubsexamples/yap-tasks; src/yap; src/emitters/yap.ts |
Plyglot: defineDialect, the CLI, the thrd and yap adapters, the conformance kit | planned | Foundation, both map families and both generators implemented; SDK typing and official editor-schema acceptance gaps recordeddocs/spec/README.md; src/core, src/adapters/thrd, src/cli |