// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC // SPDX-License-Identifier: Apache-2.0 /** * The shortcodes of the Quarto extension (quarto/_extensions/pplus/pplus.lua), as data: what each is called, what * it shows, and the options it reads. The app's "With Quarto" gallery (src/ui/quarto.ts) is written from this, * scripts/check-pages.mjs reads it to know a shortcode when it sees one, and tests/quarto.test.mjs holds it to the * names pplus.lua returns. DOM-free. */ import type { LangId } from '#core/common/types.js'; import type { StaticView, RenderRequest } from './render.js'; import { listingText } from './program.js'; import { emptyState, type PlayState } from '../core/state.js'; import { boardView } from '../core/hardware.js'; import { HW_NAMES } from './machine.js'; export type ShortcodeKind = 'rendered' | 'machine' | 'live' | 'text'; export interface ShortcodeDef { name: string; kind: ShortcodeKind; /** rendered: the view render.ts draws; live: the embed view (or `any`, chosen by view=). */ view?: StaticView | 'playground' | 'any'; /** machine: the board view it shows (its pplus-hw-), or none for the whole board. */ hw?: string; title: string; summary: string; /** The options it reads besides the shared ones (SHARED_OPTIONS). */ options: string[]; } /** Read by every shortcode that names program files. */ export const SHARED_OPTIONS = ['lingo', 'matho', 'pseudo', 'speco', 'mojo', 'asm', 'setup', 'lang', 'call', 'input', 'machine', 't', 'title', 'caption', 'collapse', 'area'] as const; /** Read by every rendered view (the machine's too). */ export const RENDERED_OPTIONS = ['code', 'numbers', 'live', 'height', 'column'] as const; export const SHORTCODES: ShortcodeDef[] = [ { name: 'pplus-run', kind: 'rendered', view: 'run', title: 'Run it', summary: 'What the program prints and returns, checked against its EXPECT lines. A Mojo file runs on the real compiler when the machine that renders has one.', options: ['compiler'] }, { name: 'pplus-steps', kind: 'rendered', view: 'steps', title: 'Step through it', summary: 'The listing beside a stepper: every step, the line it ran, what it wrote, the values after it, and what was printed so far. The run is in the page; a small script moves through it.', options: ['follow', 'max'] }, { name: 'pplus-table', kind: 'rendered', view: 'table', title: 'Table of values', summary: 'The table you would draw by hand: a column per step that changed something, a row per name.', options: [] }, { name: 'pplus-flow', kind: 'rendered', view: 'flow', title: 'Flowchart', summary: 'The routine as a flowchart, laid out from its structure; each box shaded by how often its line ran, each arrow labeled with how often it was taken.', options: [] }, { name: 'pplus-dataflow', kind: 'rendered', view: 'data', title: 'Data flow', summary: 'Which names feed which: the parameters on the left, what leaves on the right, an arrow for each assignment.', options: [] }, { name: 'pplus-lifetimes', kind: 'rendered', view: 'life', title: 'Lifetimes', summary: 'Each Mojo value from the step it is made to the step it is destroyed or moved out of, with every copy and move on the way.', options: [] }, { name: 'pplus-proof', kind: 'rendered', view: 'proof', title: 'Proof', summary: 'Every claim the specification makes (ENSURE, INVARIANT, a .speco file woven in): proved, broken by a run, or open.', options: [] }, { name: 'pplus-tests', kind: 'rendered', view: 'tests', title: 'Generated tests', summary: 'The fuzzer\'s report for each routine: what each input must do, how the inputs were made, every failure shrunk to the smallest input, every case run.', options: [] }, { name: 'pplus-check', kind: 'rendered', view: 'check', title: 'The checker', summary: 'What Programming+ finds in each file before anything runs, on the file\'s own lines, with a link to the guide.', options: [] }, { name: 'pplus-translate', kind: 'rendered', view: 'translate', title: 'Every notation', summary: 'One file in, the procedure in every notation out: lingo, matho, pseudo, speco, and Mojo generated from the pseudo (and labeled so). As tabs, columns, or the app\'s panes.', options: ['to', 'layout'] }, { name: 'pplus-machine', kind: 'rendered', view: 'machine', title: 'The machine', summary: 'An x86-64 run on the model machine: instructions, cycles on an in-order and an out-of-order core, cache misses, branches, and what bounds it.', options: [] }, { name: 'pplus-view', kind: 'rendered', view: undefined, title: 'Any view by name', summary: 'Any of the rendered views, chosen with view= (run, steps, table, flow, data, life, proof, tests, check, translate, machine).', options: ['view'] }, { name: 'pplus-hw', kind: 'machine', view: 'hw', title: 'The machine board', summary: 'The Hardware area\'s board over an x86-64 run: the listing beside the cards of a preset (registers and memory, caches, pipeline, the whole chip) or the views you name, every one drawn at every step, with a stepper.', options: ['preset', 'views', 'listing', 'stepper', 'max'] }, ...Object.entries(HW_NAMES).map(([name, id]): ShortcodeDef => { const v = boardView(id)!; return { name: `pplus-hw-${name}`, kind: 'machine', view: 'hw', hw: name, title: v.label, summary: v.blurb, options: ['listing', 'stepper', 'max'] }; }), { name: 'pplus-playground', kind: 'live', view: 'playground', title: 'The whole playground', summary: 'The app in the page: every pane, the stepper, every inspect tab and the dock. The reader\'s edits are kept in their browser; Reset brings the page\'s version back.', options: ['panel', 'build', 'dock', 'docktab', 'editor', 'side', 'dockheight', 'theme', 'ro', 'height', 'problem', 'state'] }, { name: 'pplus-embed', kind: 'live', view: 'any', title: 'One live view', summary: 'One view of the app with the code it reads: trace, table, flow, data, life, problems, proof, tests, compiler, asm, or one pane.', options: ['view', 'panel', 'build', 'theme', 'ro', 'showcall', 'split', 'height', 'problem', 'state'] }, { name: 'pplus', kind: 'live', view: 'any', title: 'The original shortcode', summary: 'A live embed, a listing, or both (show=). Pages written for it keep working.', options: ['view', 'show', 'mode', 'text', 'panel', 'build', 'theme', 'ro', 'showcall', 'split', 'height', 'problem', 'state'] }, { name: 'pplus-listing', kind: 'text', title: 'Listings', summary: 'The files as highlighted code blocks, without their header lines; a .tex file typeset as equations.', options: ['numbers', 'math', 'link', 'text'] }, { name: 'pplus-tabs', kind: 'text', title: 'Tabs', summary: 'The files as a tabset, one tab per notation.', options: ['numbers', 'math'] }, { name: 'pplus-link', kind: 'text', title: 'A link', summary: 'A link that opens the program in the app.', options: ['view', 'text'] }, ]; export const SHORTCODE_NAMES: readonly string[] = SHORTCODES.map((s) => s.name); export const OPTION_DOCS: Record = { lingo: 'a lingo file beside the page', matho: 'a LaTeX (.tex) file of equations', pseudo: 'a pseudo file', speco: 'a speco file (the specification)', mojo: 'a Mojo file', asm: 'an x86-64 listing', setup: 'the x86-64 setup block: registers and memory', lang: 'the pane that runs (default: the first of lingo, matho, pseudo, mojo, asm given)', call: 'the call to run (default: the file\'s // CALL: line)', input: 'lines INPUT reads, separated by |', machine: 'the x86-64 machine model preset', t: 'the step the stepper starts on', title: 'a title over the view', caption: 'a sentence under it', collapse: '1 folds it into a block the reader opens', area: 'bridge, dev or hw: where "open in the playground" goes', code: '1 prints the program above the view', numbers: '1 numbers the listing\'s lines', live: 'click adds "make it live", which puts the live view in its place', height: 'the live frame\'s height in px (auto: fits its content)', compiler: 'auto (the real mojo when on the PATH), on, or off', follow: 'the variables to show, comma-separated', max: 'the most steps kept (default 400; a longer machine run is sampled)', to: 'the notations to show, comma-separated', layout: 'tabs (default), columns, or grid', preset: 'the board\'s arrangement: regs (default), caches, pipeline or chip', views: 'the machine views to show, comma-separated (registers, memory, cache, pipeline, chip...)', listing: '0 leaves out the x86-64 listing', column: 'Quarto\'s column for the figure: body, page (pplus-hw\'s default), screen...', stepper: '0 draws only step t, without a stepper', view: 'which view', panel: 'the tab the playground opens on', build: 'O0 (as written) or default (as mojo build does)', dock: 'open or closed', docktab: 'the dock\'s tab', editor: 'the editor column\'s share of the width', side: 'the variables panel\'s share', dockheight: 'the editors\' share of the height', theme: 'light or dark (default: follow the page)', ro: '1: read-only, nothing saved', showcall: '0 hides the run box', split: 'the code\'s share of the frame', problem: 'a catalog problem instead of files', state: 'a state from the playground\'s Share dialog', show: 'embed, listing or both', mode: 'link: only a link', text: 'the link\'s text', math: '0 prints a .tex file as code', link: '1 adds a link to the app', }; /** The shortcode as a page writes it. */ export function shortcodeText(name: string, attrs: Record): string { const parts = Object.entries(attrs).map(([k, v]) => `${k}="${v.replace(/"/g, '"')}"`); return `{{< ${name}${parts.length ? ' ' + parts.join(' ') : ''} >}}`; } /** * A title from a state (which anyone can write into a link) as a shortcode argument the Share dialog hands to a page * author: one line, at most 120 characters, a double quote as `"` (pplus.lua reads it back), and none of the * characters that could end the shortcode or start markup in the page it is pasted into (`<`, `>`, `{`, `}`). */ export function shortcodeTitle(title: string): string { return title.replace(/[<>{}]/g, '').replace(/\s+/g, ' ').trim().slice(0, 120).replace(/"/g, '"'); } const PANES: LangId[] = ['lingo', 'matho', 'pseudo', 'speco', 'mojo', 'asm']; const list = (s: string | undefined) => (s ? s.split(/[\s,]+/).filter(Boolean) : undefined); /** * What a rendered shortcode asks render.ts for, given its options and the files beside the page (by name): the * same request pplus.lua builds, for the gallery to draw what a page would get. */ export function requestFor(view: StaticView, attrs: Record, files: Record): RenderRequest { const req: RenderRequest = { view, files: {} }; for (const p of PANES) if (attrs[p] && files[attrs[p]] !== undefined) req.files[p] = files[attrs[p]]; if (attrs.lang) req.lang = attrs.lang as LangId; if (attrs.call) req.call = attrs.call; if (attrs.input) req.input = attrs.input.split('|'); if (attrs.setup && files[attrs.setup] !== undefined) req.setup = files[attrs.setup]; if (attrs.machine) req.machine = attrs.machine; if (attrs.t && Number.isFinite(Number(attrs.t))) req.t = Number(attrs.t); if (attrs.title) req.title = attrs.title; if (attrs.max && Number.isFinite(Number(attrs.max))) req.max = Number(attrs.max); if (Number(attrs['prove-seconds']) > 0) req.proveSeconds = Number(attrs['prove-seconds']); if (attrs.views) req.hw = list(attrs.views); if (attrs.preset) req.preset = attrs.preset; if (attrs.listing === '0') req.listing = false; if (attrs.stepper === '0') req.stepper = false; req.follow = list(attrs.follow); req.to = list(attrs.to) as LangId[] | undefined; return req; } /** The state a live shortcode puts in its iframe's URL: the same one pplus.lua writes. */ export function liveStateFor(attrs: Record, files: Record): PlayState { const s = emptyState(); let first: LangId | null = null; let call: string | undefined; let input: string[] | undefined; for (const p of PANES) { const text = attrs[p] ? files[attrs[p]] : undefined; if (text === undefined) continue; s.sources[p] = listingText(text, p); first ??= p; for (const line of text.split('\n')) { const m = /^\s*(?:\/\/|%|#)\s*(CALL|INPUT):\s?(.*)$/.exec(line); if (m?.[1] === 'CALL') call ??= m[2].trim(); if (m?.[1] === 'INPUT') (input ??= []).push(m[2]); } } s.lang = (attrs.lang as LangId) || first || 'pseudo'; s.view = 'trace'; if (attrs.setup && files[attrs.setup] !== undefined) s.setup = files[attrs.setup]; const c = attrs.call ?? call; if (c) s.call = c; if (attrs.input) s.input = attrs.input.split('|').join('\n'); else if (input) s.input = input.join('\n'); if (attrs.title) s.title = attrs.title; if (attrs.t) s.t = Number(attrs.t); return s; }