@ape-egg/codecane 0.0.0-stage → 1.0.0

package/ui/viewer.js

@@ -0,0 +1,294 @@
+import vibe from '/node_modules/@ape-egg/vibe/index.js'
+import { navigate, setupSpa } from '/node_modules/@ape-egg/vibe/spa.js'
+import { setupHotModuleRefresh } from '/node_modules/@ape-egg/vibe/hot-module-refresh.js'
+import codie from '/node_modules/@ape-egg/codie/codie.js'
+
+import { mounted, pathOf, restyled } from './mounted.js'
+
+const source = new URL('/codecane/index.json', location.origin)
+
+const fetched = async (address, as = 'json') => {
+  const response = await fetch(address)
+  if (!response.ok) throw new Error(`codecane: ${address} answered ${response.status}: ${await response.text()}`)
+  return response[as]()
+}
+
+const digest = text => [...text].reduce((sum, character) => (sum * 31 + character.charCodeAt(0)) | 0, 0).toString(36)
+
+let index = await fetched(source)
+let loaded = {}
+const steps = () => Object.fromEntries(index.steps.map(step => [step.id, step]))
+const idOf = address => address.split('/')[0]
+const routes = () => [{ route: '/' }, ...[...new Set([...index.stacks.flat(), ...index.steps.map(step => step.id)])].map(address => ({ route: `/${address}` }))]
+const addressAt = (path, lane = 0) => path.split('/').filter(Boolean).join('/') || index.stacks[lane].at(-1)
+const atRoot = path => !path.split('/').some(Boolean)
+const placed = (path, current) => {
+  const lane = [current, ...index.stacks.keys()].find(lane => index.stacks[lane]?.includes(path)) ?? index.timelines.findIndex(line => line.includes(path))
+  return { lane, address: index.stacks[lane][index.timelines[lane].indexOf(idOf(path))] }
+}
+const linked = address => address ? (({ title, kind }) => ({ address, title, kind: kind ?? '' }))(steps()[idOf(address)]) : ''
+
+const folderOf = path => path.slice(0, path.lastIndexOf('/') + 1)
+const rootFirst = (a, b) => a.path.includes('/') - b.path.includes('/')
+
+const opened = async stacked => {
+  const address = new URL(steps()[idOf(stacked)].data[stacked], source)
+  const step = await (loaded[stacked] ??= fetched(address))
+  return { ...step, files: step.files.map(file => ({ ...file, folder: folderOf(file.path) })).sort(rootFirst), base: new URL(step.folder, address).href, texts: Object.fromEntries(step.changes.map(change => [change.path, change.after])) }
+}
+
+const running = page => page.files.some(file => file.path === 'index.html') ? `${page.base}index.html?revision=${digest(page.files.map(file => file.hash).join())}` : ''
+
+const text = async (page, path) => page.texts[path] ??= await fetched(`${page.base}${path}`, 'text')
+
+const changed = ({ page, drafts }) => [
+  ...page.changes,
+  ...Object.keys(drafts).filter(path => !page.changes.some(change => change.path === path)).map(path => ({ path, state: 'modified', before: page.texts[path], after: page.texts[path] })),
+]
+
+const ways = id => steps()[id].children.length + steps()[id].joins.length
+
+const cellsOf = () => index.timelines.flatMap((line, lane) => line
+  .map((id, depth) => ({
+    id,
+    key: `${lane}/${id}`,
+    depth,
+    lane,
+    forks: ways(id) > 1 ? ways(id) : 0,
+    follows: depth > 0 && ways(line[depth - 1]) === 1 && steps()[line[depth - 1]].kind !== 'seam' && !steps()[id].merges.length && steps()[id].parents.length < 2,
+  }))
+  .filter(({ id, depth }) => index.timelines[lane - 1]?.[depth] !== id)
+  .map(cell => {
+    const end = index.timelines.slice(lane).findIndex(other => other[cell.depth] !== cell.id)
+    return { ...cell, span: end === -1 ? index.timelines.length - lane : end }
+  }))
+
+const bar = ({ lane, fold, through, lit }) => {
+  const open = index.timelines.map((line, at) => at === lane || Boolean(fold && line.includes(through)))
+  return {
+    rows: open.map(on => on ? '1fr' : '0fr').join(' '),
+    cells: cellsOf().map(cell => ({
+      ...cell,
+      address: index.stacks[lane >= cell.lane && lane < cell.lane + cell.span ? lane : cell.lane][cell.depth],
+      shown: open.slice(cell.lane, cell.lane + cell.span).some(Boolean) ? 'shown' : '',
+      lit: lit.includes(cell.id) ? 'lit' : '',
+    })),
+  }
+}
+
+const barred = changes => {
+  const { selected, ...next } = { selected: $.selected, fold: $.fold, through: $.through, lit: $.lit, ...changes }
+  return Object.assign($, changes, bar({ ...next, lane: selected }))
+}
+
+const alternativesOf = (lane, at) => [...new Set(index.stacks
+  .filter(line => line.slice(0, at).join() === index.stacks[lane].slice(0, at).join() && line[at] && idOf(line[at]) !== idOf(index.stacks[lane][at]))
+  .map(line => line[at]))].map(linked)
+
+const shown = (page, lane) => ({
+  page,
+  lane,
+  selected: lane,
+  timeline: index.timelines[lane],
+  previous: linked(index.stacks[lane][index.stacks[lane].indexOf(page.address) - 1]),
+  next: linked(index.stacks[lane][index.stacks[lane].indexOf(page.address) + 1]),
+  alternatives: alternativesOf(lane, index.stacks[lane].indexOf(page.address)),
+  steps: steps(),
+  fold: '',
+  lit: [],
+  ...bar({ lane, fold: '', through: null, lit: [] }),
+  src: running(page),
+  open: '',
+  problem: '',
+  drafts: {},
+  applied: {},
+  failure: '',
+  changes: page.changes,
+})
+
+const edited = (before, after) => [...new Set([...before.files, ...after.files].map(file => file.path))]
+  .filter(path => before.files.find(file => file.path === path)?.hash !== after.files.find(file => file.path === path)?.hash)
+
+const swap = (link, href) => link.after(Object.assign(link.cloneNode(), { href, onload: () => link.remove() }))
+
+const restyle = (doc, paths) => doc.querySelectorAll('link[rel="stylesheet"]').forEach(link => {
+  const url = new URL(link.href)
+  if (!paths.includes(url.pathname)) return
+  url.searchParams.set('t', Date.now())
+  swap(link, url.href)
+})
+
+const relink = async (doc, page, drafts) => {
+  const links = [...doc.querySelectorAll('link[rel="stylesheet"]')]
+  const sheet = restyled(page, drafts, path => text(page, path))
+  const hrefs = await Promise.all(links.map(link => sheet(link.href)))
+  links.forEach((link, at) => hrefs[at] !== link.href && swap(link, hrefs[at]))
+}
+
+let pause
+const preview = async () => {
+  const { page, drafts, applied, src } = $
+  const paths = Object.keys({ ...applied, ...drafts }).filter(path => drafts[path] !== applied[path])
+  if (!src || !paths.length) return
+  const frame = document.querySelector('stage iframe').contentDocument
+  const styled = paths.every(path => path.endsWith('.css')) && frame.URL === src
+  const next = styled ? src : await mounted(page, drafts, path => text(page, path))
+  if (styled) await relink(frame, page, drafts)
+  if ($.drafts === drafts) Object.assign($, { applied: drafts, src: next })
+}
+
+const reports = {
+  ran: () => $.failure = '',
+  failed: ({ message, source, line }) => $.failure = { message, at: source && `${pathOf($.page, source)}:${line}` },
+}
+addEventListener('message', ({ source, data }) => source === document.querySelector('stage iframe')?.contentWindow && reports[data.codecane]?.(data))
+
+const first = placed(addressAt(location.pathname))
+window.$ = vibe({ name: index.name, version: index.version, editable: index.editable, kinds: { merge: 'Merge', seam: 'Seam' }, through: null, panel: 50, dragging: false, closing: false, fullscreen: false, returning: false, root: atRoot(location.pathname), ...shown(await opened(first.address), first.lane) })
+const titled = address => document.title = `${index.name} · ${steps()[idOf(address)].title}`
+titled(first.address)
+
+setupSpa({
+  routes: routes(),
+  onNavigate: async ({ path }) => {
+    const { lane, address } = placed(addressAt(path, $.selected), $.selected)
+    const page = await opened(address)
+    if (addressAt(path) !== addressAt(location.pathname)) return
+    Object.assign($, { root: atRoot(path), ...shown(page, lane) })
+    titled(address)
+  },
+})
+
+window.codecane = {
+  step: address => navigate(`/${address}`),
+  fold: parent => barred({ fold: $.fold && $.through === parent ? '' : 'unfolded', through: parent }),
+  light: (...ids) => barred({ lit: ids }),
+  pick: (event, id, lane, span) => {
+    const sibling = id !== $.page.id && steps()[id].parents.join() === steps()[$.page.id].parents.join()
+    const at = index.timelines[lane].indexOf($.page.id)
+    const before = at > -1 && at < index.timelines[lane].indexOf(id)
+    if (!$.fold || sibling || before || ($.selected >= lane && $.selected < lane + span)) return
+    event.preventDefault()
+    const address = index.stacks[lane][at]
+    if (address && address !== $.page.address) return navigate(`/${address}`)
+    barred({ selected: lane, fold: '' })
+  },
+  open: async path => {
+    await text($.page, path)
+    Object.assign($, { panel: $.open ? $.panel : 50, open: path, closing: false })
+  },
+  grab: ({ currentTarget, pointerId }) => {
+    currentTarget.setPointerCapture(pointerId)
+    $.dragging = true
+  },
+  drag: ({ clientY, currentTarget }) => {
+    const { bottom, height } = currentTarget.closest('stage').getBoundingClientRect()
+    $.panel = Math.min(100, Math.max(30, (bottom - clientY) / height * 100))
+  },
+  snap: () => Object.assign($, { panel: Math.round($.panel / 10) * 10, dragging: false }),
+  run: async () => {
+    clearTimeout(pause)
+    await preview()
+    $.closing = true
+  },
+  settle: () => $.closing && Object.assign($, { open: '', closing: false }),
+  expand: () => document.documentElement.requestFullscreen(),
+  returned: () => $.returning && Object.assign($, { fullscreen: false, returning: false }),
+  save: async forks => {
+    const { open, page, drafts } = $
+    const response = await fetch(`/codecane/save/${open}?at=${encodeURIComponent(page.address)}${forks ? '&forks' : ''}`, { method: 'PUT', body: drafts[open] })
+    if (response.status === 409) {
+      $.problem = await response.text()
+      return
+    }
+    if (!response.ok) throw new Error(`codecane: saving ${open} answered ${response.status}: ${await response.text()}`)
+    index = await fetched(source)
+    loaded = {}
+    Object.assign($, shown(await opened(page.address), $.lane))
+  },
+}
+
+document.addEventListener('fullscreenchange', () => Object.assign($, document.fullscreenElement ? { fullscreen: true } : { returning: true }))
+
+const reread = async () => {
+  index = await fetched(source)
+  loaded = {}
+  const { page: before, lane: current, fold, through, lit, open, drafts, applied, failure, problem, src } = $
+  const page = await opened(before.address)
+  const { lane } = placed(page.address, current)
+  const paths = edited(before, page)
+  const styled = paths.every(path => path.endsWith('.css'))
+  const kept = page.files.some(file => file.path === open) ? open : ''
+  if (kept) await text(page, kept)
+  if ($.page !== before) return
+  Object.assign($, {
+    ...shown(page, lane),
+    ...bar({ lane, fold, through, lit }),
+    fold,
+    lit,
+    open: kept,
+    drafts,
+    problem,
+    changes: changed({ page, drafts }),
+    src: styled ? src : running(page),
+    applied: styled ? applied : {},
+    failure: styled ? failure : '',
+  })
+  titled(page.address)
+  if (styled && src) restyle(document.querySelector('stage iframe').contentDocument, paths.map(path => new URL(path, page.base).pathname))
+  await preview()
+}
+
+if (index.editable) {
+  const events = new EventSource('/codecane/events')
+  const on = (event, update) => events.addEventListener(event, ({ data }) => update(JSON.parse(data)))
+  setupHotModuleRefresh({
+    subscribe: ({ componentUpdate, pageUpdate }) => {
+      on('component-update', ({ path }) => componentUpdate(path))
+      on('page-update', pageUpdate)
+      on('style-update', ({ path }) => restyle(document, [path]))
+    },
+  })
+  on('steps-update', reread)
+}
+
+const diffs = new WeakMap()
+const redraw = ({ changes, drafts }) => document.querySelectorAll('changes-list codie').forEach(el => {
+  const change = changes.find(change => change.path === el.dataset.path)
+  const code = drafts[change.path] ?? change.after
+  if (!diffs.has(el)) {
+    el.toggleAttribute(`highlight-${change.path.split('.').pop()}`, true)
+    diffs.set(el, codie({ el, diff: true, numberedRows: true, before: change.before }))
+  }
+  if (diffs.get(el).before !== change.before) diffs.get(el).before = change.before
+  if (diffs.get(el).code !== code) diffs.get(el).code = code
+  const header = el.parentElement.querySelector('change-header')
+  header.querySelector('added').textContent = `+${el.querySelectorAll('.codie-diff-added').length}`
+  header.querySelector('removed').textContent = `−${el.querySelectorAll('.codie-diff-removed').length}`
+})
+
+let editor
+$.on('afterUpdate', ({ page, open, drafts }, previous) => {
+  if (open && open === previous.open && !(open in drafts) && page.texts[open] !== previous.page.texts[open]) editor.code = page.texts[open]
+  if (!open || open === previous.open) return
+  editor = previous.open ? editor : codie(document.querySelector('stage codie'))
+  Object.assign(editor, {
+    language: open.split('.').pop(),
+    code: $.drafts[open] ?? page.texts[open],
+    editable: true,
+    numberedRows: true,
+  })
+  editor.onEdit = ({ raw }) => {
+    const { [open]: _, ...others } = $.drafts
+    $.drafts = raw === $.page.texts[open] ? others : { ...others, [open]: raw }
+    $.changes = changed($)
+    $.problem = ''
+    clearTimeout(pause)
+    pause = setTimeout(preview, 300)
+  }
+})
+
+$.on('ready', () => {
+  redraw($)
+  $.on('afterUpdate', redraw)
+})

package/workflow.md

@@ -0,0 +1,81 @@
+## codecane
+
+This project is built up step by step with [codecane](https://github.com/kkortes/codecane). Each folder in `steps/` holds only what its step adds or changes. `codecane build` stacks the steps into complete, runnable folders, one per step, and fails if a step no longer runs.
+
+### Steps
+
+- `steps/<id>/` holds the files the step adds. `steps/<id>.html` beside it is its story, and its `<h1>` names the step.
+- A step changes a file from an earlier step with a patch, `steps/<id>/<path>.patch`, which stores only the lines it changes. A patch is unified-diff hunks (`@@ -8,7 +8,9 @@`, then lines starting with a space, `-` or `+`). It applies exactly at its line numbers: there is no fuzz and no searching.
+- A step continues the step before it in natural order (`2` before `10`) unless its `codecane.json` names a `parent`. The parent can be any step, as long as parents never lead back to the step itself, and `"parent": null` starts a new root. Steps stack parents first. Where a step has several children, they follow natural order of their ids, and the first one leads the default timeline.
+- `steps/<id>/codecane.json` is optional and never stacked:
+  - `parent`: the step this one continues. Two steps naming the same parent are a pivot, and from there the timelines fork. A list of steps continues all of their timelines together. See Continuing timelines together.
+  - `merges`: steps on other timelines whose timelines this step merges into its own. See Merging timelines.
+  - `removes`: paths of earlier files this step takes away.
+  - `overrides`: paths of earlier files this step replaces with a full copy. A copy that isn't listed fails the build, so every full copy is a deliberate choice. Prefer a patch.
+- Nothing is generated: every stacked file is a step's file with the later steps' patches applied.
+- A change to a step reaches every later step on the next build, because later steps hold no copies.
+- Each step stores the code it wrote, and a replay reuses that code exactly. Nothing is ever written again on a replay, so every replay gives the same code.
+- `steps/<id>.check.js` is the step's optional check, never stacked. Its default export gets the stacked step's files as `{ path: text }` and throws when the step doesn't do what it should. A step without one still stacks and builds, and is marked untested.
+
+### Adding a step
+
+- Add new files, and patch earlier files only where the new code has to be wired in, such as a `<script>` tag or an import line.
+- The easy way to write a patch: copy the earlier file into the new step and edit the copy. While `codecane dev` runs, it turns the copy into a patch that holds only the changed lines as soon as the writes settle. Without it, run `codecane patch <id> <path>`. In a step with several parents, the copy is made from and patched against the first parent's timeline.
+- Pick an id. A number continues the step before it without a `parent`. A name, such as `moving-the-center`, names its `parent` in its `codecane.json`. Among steps with the same parent, the id that sorts first leads the default timeline.
+- Write the story: an `<h1>` with the step's name, and a short account of what it adds and why.
+- Add `steps/<id>.check.js` when the step does something a check can prove.
+
+### After editing any step
+
+- **Run `codecane check` after every edit to a step folder.** It replays every step and runs its checks. When everything passes it says so in one line. Otherwise it stops at the first step that breaks and says why: a patch that no longer applies, with the step, the file and the lines, or a check that fails, with its message. The stored steps must always stack cleanly. Never leave a step folder in a state where `codecane check` fails.
+- `codecane dev` watches `steps/`, whoever edits it: an agent, the developer or any other tool. Once the writes have settled, it saves copies of earlier files as the step's patches, rebases the later patches, and replays from the changed step forward. When everything passes it says nothing. Otherwise it stops at the first step that breaks and says why. A save in the viewer replays the same way.
+- Edits made in the viewer, or on disk while `codecane dev` runs, rebase the later patches right away. A later patch whose changed lines only moved is rewritten to the new line numbers. A save in the viewer that would break a later patch is refused with the step and lines. A change on disk that breaks one is reported in `codecane dev`'s output, and `codecane check` fails until it's resolved.
+- If a later patch no longer applies, resolve it in that step: rewrite its patch against the new lines, or revert the edit that broke it.
+
+### Fixing and refactoring
+
+- A fix goes into the step that last changed the code. That is the step that brought the file, or the last step that patched it. The viewer shows it as "last changed in step N". The fix then flows into every later step.
+- If a new step needs a hook that doesn't exist yet, add the hook to the step that owns the code. Don't work around it in the new step.
+- A refactor is only ever a deliberate step of its own. It patches, overrides or removes the files it reshapes, and its story says why.
+
+### Continuing timelines together
+
+A pivot's timelines can be alternatives, such as a square and a hex floor. When the next steps should be written once for all of them, but each timeline should keep what it chose, don't merge them. Continue them together:
+
+- Give one step several parents: `{ "parent": ["<step>", "<other-step>", …] }`. The first leads the default timeline.
+- That step, and every step after it, stacks once per timeline, onto that timeline's own files. Nothing is combined, so a timeline never carries another timeline's code.
+- Every step can be visited at `/<step>`, which shows it with the default fork at each fork on the way. Once forks have been chosen, the default one included, its address is `/<step>/<hash>/<hash>…`: the short hashes of the step taken at each fork before it, earliest first, such as `/moving-the-center/05adc6a`. Only forks before the step count, so a step before any fork, or the step a fork takes, never carries one. The viewer keeps to the timeline you are on with every click. With the fork marker unfolded, pressing a fork navigates straight to it when the step you are on comes before it, such as Canvas, or is itself a fork beside it, such as World hex surface beside World triangle surface. From a step after the fork, pressing a step on another fork picks that fork without leaving the step you are on: the address's hashes change to the new fork, such as `/moving-the-center` becoming `/moving-the-center/05adc6a`, and the preview reruns on it. Pressing a step on the picked fork, once it is picked, navigates to that step. `codecane stack <address> --out <dir>` writes that step alone, ready to deploy.
+- The step's patches have to apply on every timeline, and its checks run on every one. Where the timelines differ in what the shared steps need, write a seam: a small internal API that the shared steps use, filled in on each timeline by the step that owns that code there, the way a missing hook is added.
+- A step with several parents that holds code of its own is a **seam**. It shows in yellow, with the fork icon mirrored, like a merge step's seam, and it is always needed: its code is what the timelines share from there on. A step with several parents and no code of its own just joins them, in the normal colour.
+
+Merge instead when the timelines each add something the result should hold together.
+
+### Merging timelines
+
+Timelines fork wherever steps share a parent, and any number of them can merge again at any step. Merging never merges text. A merge step replays the other timelines' steps onto its own timeline, using each step's stored code exactly, and then runs the checks of every step on all the timelines it joins. The viewer only shows merges. Agents make them, like this:
+
+1. **Try it first.** `codecane merge <step> <other-step…>` replays the other steps' timelines onto `<step>`'s timeline and writes nothing. It reports one of three things: a clean merge, a seam that is needed and why, or the first step that breaks and why. Tell the developer the result.
+2. **Go ahead only once the developer confirms.** Add one step whose `codecane.json` says `{ "parent": "<step>", "merges": ["<other-step>", …] }`, and a story saying what came together. If it needs a seam, write it only together with the step that needs it.
+3. **Then the usual loop takes over.** `codecane dev` and `codecane check` replay the merge with everything else, and report any later step that breaks because of it.
+
+A merge step is one of three kinds. codecane decides the kind by replaying and running the checks. It never guesses:
+
+- **Merge**: the step holds no code of its own. Every step it brings replays cleanly, and every check passes on both sides. It shows in the normal colour.
+- **Seam**: the timelines differ, so a step won't replay or a check fails. The step then holds a seam: a small internal API, what each timeline fills in, and the code that makes the brought steps replay. The viewer shows the steps that required it and why. It shows in yellow, with the fork icon mirrored.
+- **Seam no longer needed**: a replay without the seam's code still passes every check, here and in every later step. The timeline leaves it out, and `codecane check` says so.
+
+Every step has a short hash, generated once when codecane first sees the step and stored as `hash` in its `codecane.json`. `codecane check`, `build`, `dev` and the other commands give a new step one. A seam lives in `parts/<hash>/`, beside `steps/`, with its story at `parts/<hash>.html`: its short hash is its id and its folder name, and later steps name it by that hash. Its story has no `<h1>`; the viewer titles it `Seam <hash>`. `codecane check` gives a seam written in `steps/` its hash and fails with where in `parts/` to move it, and fails on a step in `parts/` that holds no seam. A seam that isn't needed is never written.
+
+A step's kind is the result of its last replay:
+
+- Adding steps after a merge never changes it. When a later step needs what the timelines do differently, put a seam right before that step: a step that names the same timelines in `merges` again and holds only the seam.
+- Editing a step from before a merge replays the merge again. If its steps no longer replay cleanly, or a check fails, the merge needs a seam. codecane stops there and says why, and an agent or the developer writes the seam into that step.
+
+### Commands
+
+- `codecane check`: replays every step and runs its checks, and stops at the first step that breaks with why. It names the untested steps and any seam that is no longer needed, which the timeline leaves out.
+- `codecane merge <step> <other-step…>`: tries merging the other steps' timelines into `<step>`'s timeline, and writes nothing.
+- `codecane patch <id> [path…]`: turns a step's copies of earlier files into patches.
+- `codecane dev`: the viewer at `/`, every stacked step at `/steps/<id>/`, live from `steps/`. It watches `steps/`, turns copies into patches, rebases later patches and replays from each changed step forward, and the open viewer updates in place without reloading. Saving in the viewer writes to the step that last changed the file.
+- `codecane build`: writes `dist/` (every stacked step, its JSON data and the viewer) and checks that every step runs. `--bare` leaves out the viewer.
+- `codecane stack <address> --out <dir>`: writes one step on one timeline, such as `moving-the-center/05adc6a`; `codecane stack moving-the-center` writes it with the default forks.