#>software_surface

plain-text systems interaction grammar projection surfaces tool probes

software

Software Surface

Software

A component is a small machine for arranging attention.

syntax
grammar
projection
route
artifact

Spw is the throughline: a readable [plain-text format] that tools can address, query, and project. This page introduces the syntax, the (operator grammar), and the <small demos> that make the idea concrete.

The language design philosophy is simple to state and hard to honor: authored text should remain human-readable, structure should stay stable enough for tools to navigate, and every richer surface should be a deterministic projection rather than a second, drifting source of truth. That is the technical reason the site can also behave like documentation, lore, and a seedbed for future sites.

The larger public goal is simpler than the implementation: help people who do not code yet feel that software can describe actual phenomena. A program can model pressure, sequence, timing, budgets, queues, memory limits, branching states, and consequences. Once that becomes visible, a business plan, classroom routine, worldbuilding system, or production workflow stops feeling mystical and starts feeling discussable.

Read this surface like an academic cookbook for theory. A parser is a recipe for turning syntax into structure. A type is a pantry label that prevents the wrong ingredient from entering a dish. An interface is a service contract. A scheduler is kitchen timing. A renderer is plating. These analogies are not replacements for formal study; they are ramps that help a returning learner keep the formal terms warm.

CSS is useful here because it already teaches constraint thinking: width, overflow, alignment, inheritance, fallback, and responsive tradeoffs. Lower-level programming languages add a more direct vocabulary for memory, allocation, latency, and failure. Add combinatorics and dimensional expansion, and a small set of rules can generate a surprisingly large world of possible outcomes.

The software route should explain its machinery without making every reader feel trapped in a dashboard. A runtime feature can appear as a field mark: a visible handle that says what can be tuned, what script owns the behavior, and where the same concept appears elsewhere.

HTML scavenger hunt

Use the page source to find the elements that carry the job. The game is to read the structure, name what each tag protects, and extend the same pattern without inventing a new wrapper unless you need one.

headerFind the route stance and the title that frames the page.
navFind the routes that help a reader travel or compare.
mainFind the source idea the page is trying to teach.
articleFind the self-contained body of the lesson.
sectionFind a named chunk that can grow or split without losing its purpose.
asideFind the related routes and side notes that widen the field.
figureFind the examples, screenshots, and evidence that make the idea concrete.
footerFind the afterword, the exits, and the durable links that remain once the reading is done.

If you want to extend the same structure on other pages, compare this route with component glossary, design hub, website field guide, and semantic settings. Those routes show how the same landmarks can carry different kinds of meaning without changing the HTML backbone.

Software engineering theory enters here as discipline rather than decoration: invariants keep meaning stable, interfaces make promises explicit, parsers turn syntax into structure, schedulers decide when behavior arrives, and renderers project the same model into different surfaces. Spw is useful when those layers stay close enough that a reader can learn the theory by inspecting the page.

Invariant ground

Plain text is the stable source. HTML, CSS, JS, and future tools should explain their relationship to it instead of replacing it.

Runtime precision

Mount timing, module reasons, and data attributes make behavior auditable enough for QA, teaching, and extension work.

Projection genres

A route can become a card, diagram, prompt, playable scene, or sibling site when the semantic kernel is legible.

The programming-theory neighbor is not only parsing. It is the discipline of separating source language, intermediate representation, scheduler, renderer, and effect. Spw semantics are useful when those layers remain named enough that a learner can inspect the transformation rather than merely trusting the result. That same habit helps a model or collaborator extend the page: keep the landmark, keep the role, and add depth in the nearest semantic container.

Why software lives here

software on this site is a media system, not just an implementation detail.

Best readers

developers, systems designers, toolmakers, returning students, parents, and worldbuilders who need readable structure.

Leave with

route scaffolds, operator pages, memory-management handles, render-thinking ramps, and durable documentation for later work.

Read the sections in order if you want the gradual path: first the source idea, then the grammar, then interactive codeblocks, components, external probes, and the text-editing application context. If you want the theory neighbors behind parser design, jump from here into the parser field guide, renderers, schedulers, knowledge bases, algorithm visualization, differential lambda calculus, complexity, scale intuition, statistical analysis, category theory, and number theory.

A dense software weather collage of parser circles, fibers, symbols, and measured structure. — **Parser weather** Symbols, measures, and charged intervals keep this software surface close to the parser map, complexity budgets, and modular rhythm.

#["language_philosophy"]

Language Design Philosophy

philosophy

The language is not trying to win by density alone. It is trying to keep source legible while giving tools clearer contracts about structure, timing, and projection.

Another way to say it is: programming languages help model ideas, CSS helps model constraints, and lower-level systems work helps model scarce resources. Put those together and you get a way to project how a project might develop before the social and financial costs become harder to change.

Orient

Meet the language as a readable field

Re-open the software surface#> Start from the plain-text promise before branching into syntax or runtime detail.
Use the author craft ramp.craft The surrounding craft route keeps the language tied to real publishing practice.
Move into the operator atlas#spw The atlas gives the token-level map that this broader philosophy depends on.

Inspect

Inspect how structure stays legible

Read the syntax surface^syntax The source, syntax, and surface views should remain traceable to the same file.
Follow parser lenses?parse Parser work is where readable structure becomes a machine-readable contract.
Inspect browser and TypeScript constraints$browser Projection only stays honest if the target substrate and runtime limits stay visible.

Commit

Prefer actions that deepen authorship

Use the interactive codeblocks@demo Interaction should clarify how source and surface relate instead of replacing the source.
Enter the pretext lab@pretext A local lab is where semantic moves can be tried without faking a polished app shell.
Inspect component commitments@component Components should stay downstream of named structure, not become a second source of truth.

Project

See where the same source can manifest

Renderers>render Projection becomes visible when the same semantic unit appears in a different output form.
Compression>compress Compression pressure reveals which semantic distinctions are structurally essential.
Schedulers>time Timing and projection belong together once authored structure starts appearing in several encounters.

Readable source is the primary artifact

The file should still work as something a person can read out loud, diff in git, annotate in an editor, or share in a chat. Tooling depth is valuable only if it grows from that durability instead of replacing it.

Names create handles

Frames, layers, and bindings are useful because they make portions of the file addressable. Once a region has a stable name, a plugin, parser, renderer, or website can refer to the same thing without inventing a second map.

Operators say intent, braces say topology

An operator should tell the reader what kind of semantic move is being attempted. A brace should tell the reader what kind of container or boundary is present. That split keeps the model composable and easier to generalize across tools.

Projection should be deterministic

A projected HTML card, a plugin outline, a prompt brief, and a public guide page should all be traceable back to the same authored source. Projection is manifestation into another substrate, not silent mutation of the original text.

Tooling should deepen authorship

The VS Code plugin, LSP client, website, and later projections are not the point by themselves. Their job is to help an author keep more structure visible, ask better questions of the text, and move between realities without losing semantic continuity.

Human and machine readers deserve the same map

I want the file, plugin, and website to be different projections of one semantic field. That means a person following a heading and a tool following a frame id should be able to converge on the same unit of meaning.

#>curricularize_codebase

Curricularize Your Codebase

thesis

A codebase becomes more valuable when it can teach its own structure. The goal is not to convert everything to TypeScript for coverage optics. The goal is to put types where they become durable public reasoning: event contracts, page data, timing vocabulary, component roles, and business-critical seams.

Marketability

Make the architecture legible on first contact

Show the site as a proof surface.site The public page should demonstrate the architecture instead of only describing it.
Frame the service offer$offer Clients can buy clarity, onboarding, and risk reduction, not just implementation hours.

Architecture

Name contracts before chasing sprawl

Use TypeScript where contracts matterts Event payloads, runtime environment boundaries, route metadata, and page data earn types early.
Keep seams visible#arch Readable architecture exposes joins so future contributors can reason about change.

Business Value

Tie refactors to decisions people recognize

Use staff-level judgementadvisory The important question is what deserves stabilization now, later, or never.
Scope around leveragequote Small typed seams can be worth more than broad rewrites when they clarify core risk.
Fund the next render passqueue Queues, checkpoints, and named passes make memory and timing easier to budget before scale turns confusion into cost.

Education

Let the codebase become a curriculum

Connect structure to learninglearn Good naming and typed examples reduce the hidden prerequisite load for the next reader.
Expose the page data modeldata A public route should be able to say what data it carries and why the component exists.

Events become a vocabulary

Frontend events should read like a small language: stable names, predictable payloads, clear timing, and a known place where cross-feature signals pass through.

Memory blocks stay visible

Buffers, queues, checkpoints, and caches should be named plainly enough that a teammate, investor, or future maintainer can tell what the system remembers, when it releases pressure, and what happens when it fills up.

Pages carry explainable data

Route metadata, related routes, feature gates, and semantic attributes should help the page explain what it is for before a reader digs through implementation details.

Components have rationales

A component is more maintainable when its slots, states, data attributes, and interaction boundaries are visible enough to critique.

Types mark the load-bearing seams

The budget-conscious move is to type the contracts that organize behavior, then let ordinary HTML and CSS keep carrying the readable public surface.

Render budgets stay teachable

Video processing is a good grounding metaphor here: frame budgets, staging buffers, and decode / encode passes make time and memory visible enough to reason about before performance turns into mystery.

%[semantic_fields]

Perspective, Potential, Dimension, Salience

fields

Cards and panels can act as portable Spw modules. If the boundary is stable enough to copy, link, or hydrate later, it should also be able to declare whose view it centers, how ready it is, which dimensions dominate, and how loudly it should call attention.

perspective Who or what the module centers

Use perspective to say whether a card is speaking from a reader view, a public field-guide voice, a collaborative room, or a system-level lens.

potential How ready the module is to do more

Potential distinguishes latent notes from modules that are ready to be copied, hydrated, or promoted into a stronger browser-facing component.

dimension Which axes matter in this encounter

A module can bias toward syntax, gesture, memory, routing, or publication. The dimensions do not change the source; they change how the same source is read.

salience How forcefully the module should ask for attention

Salience should be modulatable. A quiet card can become near or strong when focused, selected, or promoted by the current reading context.

This is the shape I want for copyable and hydratable browser modules: the HTML stays legible, the module keeps its declarative fields, and the later browser runtime can read those same attributes instead of inventing a second contract.

<article class="frame-panel"
  data-spw-module="parser_lens"
  data-spw-module-copy="fragment"
  data-spw-module-hydration="ready"
  data-spw-perspective="system"
  data-spw-potential="emergent"
  data-spw-context-bias="analysis"
  data-spw-context-projection="publication"
  data-spw-dimension="syntax surface"
  data-spw-salience="near">
  ...
</article>

Later, richer blocks can carry context gradients too. A selected <context># bias or <context>@ projection should be able to modulate the same module without requiring a rewritten component contract.

#>spw_syntax_surface

syntax

Public Reference Surface

Spw Syntax

Spw keeps the file readable while giving tools clearer structure to work with. The source stays visible; LSP servers, clients, and projection tools get named frames, operators, and references they can navigate. This page is the public edge of the deeper spw-workbench runtime and design work, and the nearby parser route shows how those structures become concrete.

#>note
#:layer #!pragmatics

^"summary"{
 claim: "Files should remain legible."
 tags: ["durable", "portable", "inspectable"]
}

.orientation

Orientation

thesis

plain-text first frame-based queryable projection-ready interactive codeblocks

The rest of the page builds from these five ideas: keep text readable, name useful regions, make those regions queryable, project them into views, and let codeblocks participate.

If you are coming from writing, illustration, or book communities instead of software, start with the author craft ramp and come back here when the file and syntax pieces start to feel useful.

~"algorithm_scale_cluster"

Algorithm + Evidence Cluster

cluster

These routes keep software talk grounded when a procedure has to survive real scale, evidence pressure, and human consequence.

Algorithm visualization

Use pictures, invariants, and failure modes so search, ranking, compression, and traversal become discussable across roles.

route: algorithm visualization

Scale intuition

Keep claims anchored to the right layer when a local rule begins touching teams, rooms, or public systems.

route: scale intuition

Statistical analysis

Bring in baseline, variance, sampling, and intervention language when the software surface needs evidence instead of vibes.

route: statistical analysis

#>comparison

Source Comparison

source

.markdown_base

Markdown base

## Note

Files should remain legible.

- durable
- portable
- inspectable

^"spw_frame"{

Spw frame

#>note
#:layer #!pragmatics

^"summary"{
 claim: "Files should remain legible."
 tags: ["durable", "portable", "inspectable"]
}

The text still reads normally, but parsers, metadata systems, interactive codeblocks, and projection layers now have stable handles.

?[core_forms]

Core Forms

forms

Name a frame so it can be linked, queried, and projected.
Mark the interpretive layer or role of a frame.
Hold structured content in a stable, inspectable body.
Carry references, paths, or literal anchors.
Store questions, probes, or interactive interpretive units.

^"composite_example"{

Composite Example

composite

#>frame_name
#:layer #!meaning_time

^"object"{
 key: "value"
 list: ["one", "two"]
 ref: ~"./other-surface.spw"
}

?["What changes when a note becomes queryable?"]{
 !probe{ "project this frame into outline, graph, and editable card views" }
}

#>spw_grammar_surface

grammar

Grammar as Interface

Spw operator prefixes are not decoration. Each token names what kind of thing follows and how an interface should let someone approach it.

#>name	frame declaration — names a unit, makes it linkable, queryable, and addressable by tooling
#:layer	layer marker — marks the interpretive role of a frame (`!pragmatics`, `!meaning_time`, `!ux`)
.member	baseline — returns attention to a local default, member, or settled lens
^"name"{ }	object — holds structured, inspectable content; the body remains legible plain text
~"path"	reference — carries a path, named anchor, or literal; points outward without breaking the file
?[probe]{ }	probe — stores a question, query, or interactive unit; signals inquiry at the structural level
@action(...)	action — commits a local behavior or projection; the imperative operator
*stream	stream — connects to dynamic or event-driven content; marks where data flows in
&merge	merge — overlays fields so comparison and integration can stay inspectable
=binding	binding — names, pins, or categorizes a local value so it can be reused
$meta	meta — reflects on the medium, trace, or register itself
%normalize	normalize — adjusts salience or scale so comparison remains honest
!pragma	pragma — encodes a runtime constraint or interpretive hint; metadata about the frame itself
>surface	surface — a projected or rendered view; the output end of a frame pipeline

The local .spw/ bridge now routes through .spw/surfaces.spw and .spw/conventions/site-semantics.spw before it reaches the installed workbench canon, so the same operator map that shapes this page also informs /play/rpg-wednesday/ through shared naming, selection, liminality, and interface-pattern surfaces.

#>interaction_model
#:surface #!ux
#:layer #!pragmatics

^"interaction_principles"{
 first_impression: "Calm, legible, and technically grounded."
 pacing: "Reveal depth progressively: headline -> proof -> artifact -> context."
 affordance: "Links should read like intentional paths, not a directory dump."
 cohesion: "Typography, spacing, and section naming reinforce a sense of order."
}

^"interaction_overhaul"{
 frame_activation: "Frames visibly activate when sigils or cards are used."
 sigil_role: "Sigils act as anchors, lenses, and controls — not decorative labels."
 motion: "Motion reads as state transition and projection, not ornamental animation."
}

^"design_bridge"{
 principle_1: "Syntax can act as interaction grammar: structure should teach behavior."
 principle_2: "Spatial variation feels governed and mirrored, not arbitrary."
 principle_3: "Restraint, stable placement, and navigable references are product depth."
}

@rotate(surface)

Interactive Codeblocks

demo

This is the smallest useful demonstration: one authored unit can move between source, syntax, and rendered surface.

# Local-first note

Files should remain legible.

- durable
- portable
- inspectable

[[Tooling]]

#>local_first_note
#:layer #!pragmatics

^"note"{
 title: "Local-first note"
 claim: "Files should remain legible."
 tags: ["durable", "portable", "inspectable"]
 links: ["Tooling"]
}

^"spw_component_surface"{

Spw-backed Components

components

The target is not a parser bolted onto every page. It is a progressive component system where authored Spw blocks, semantic HTML, shared registers, and small scripts agree about structure.

Semantic host

HTML landmarks, headings, lists, controls, and figures remain the accessibility baseline. Components enrich that host instead of replacing it.

Register behavior

Navigator, console, future mirrors, and Spw widgets should read shared route, focus, projection, and region state instead of inventing private state.

Prefix / postfix symmetry

Keyboard flows can choose intent first; touch inspection can choose target first. Equivalent outcomes should leave the same semantic trace.

Graceful no-op

If a token has no action yet, the interface should explain the missing target or show the contract instead of making exploration feel broken.

Blocks and scripts

Future Spw blocks can become widgets, inspect panels, capture frames, spell boards, or LSP-backed navigation when their contracts are stable.

>pretext_probe

External Probe: Pretext.js

external

#>pretext_field_lab Pretext Field Lab A live route for exploring text measurement, line breaking, and responsive layout without DOM reflow.

Why it fits here

Pretext.js fits because it makes text projection visible. Authored text stays legible, while the rendered surface becomes measurable, responsive, and deliberate.

This is an external-library probe, but it follows the same pattern as the rest of the page: source first, then measurable projection.

@text_editing_application

Text editing applications with Spw in mind

application

A current reason this matters is Obsidian, but the broader utility is larger than one company: the same plain-text and projection questions show up across note-taking, editing, plugins, and teaching surfaces.

Plain text stays

Files remain portable and human-readable. Spw does not replace the trust model of readable files; it adds structure around them.

Frames over anonymous blocks

Sections become named units with stable references, clearer relationships, and better projection options.

LSP-navigable semantics

Metadata can stay plain text while LSP servers and clients make roles, layers, references, and interactions navigable.

Interactive codeblocks

Codeblocks can move between source, syntax, and rendered views without becoming detached widgets.

Clients as projections

Editors, plugins, and clients gain a richer substrate instead of just more UI state to manage.

Literate curricula

The interface becomes part of the learning model: interaction reveals structure, supports reflection, and keeps plain text connected to the lesson.

~"design_influences"

Design Influences

influences

Literate UI operator gestures as navigation primitives, so syntax teaches interaction.
Symmetry UI Design spatial behavior follows symmetry while interaction follows operator physics.
Ocean UX expert reward comes from stable placement, reference-driven navigation, and repeated familiarity.
Style Currents style should be recognizable and reproducible, not ornamental drift.

These ideas come from the `spw-workbench` design notes and are translated here into a public site context.

*pipeline

Pipeline

pipeline

Plain text -> Spw frame -> parser -> LSP server -> client projection -> literate curriculum

The goal is plain text with more usable structure around it.