@lincyaw/kernel 1.0.0-rc.13 → 1.0.0-rc.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincyaw/kernel",
-  "version": "1.0.0-rc.13",
+  "version": "1.0.0-rc.14",
   "description": "Presmium's shared kernel: the IR and plugin contracts, the service registry, anchors and checks",
   "license": "Apache-2.0",
   "repository": {
@@ -15,6 +15,7 @@
     "ir"
   ],
   "type": "module",
+  "sideEffects": false,
   "engines": {
     "node": ">=22.19"
   },

package/src/contracts/workspace.ts

@@ -94,6 +94,8 @@ export interface DocumentSummary {
   description?: string
   lang?: string
   tags?: string[]
+  /** Whether its metadata asks for a presentation (`renderers.slides`), which a site serves below its pages. */
+  slides?: boolean
 }
 
 /** @experimental The workspace service's answer to `documents`. */

package/src/embed.ts

@@ -0,0 +1,26 @@
+/**
+ * What a page tells the page that embeds it in a frame, as `postMessage` to its parent: whether its current slide is
+ * drawn (no component is still loading) and the state of its lecture. An embedding page (a site's home page playing a
+ * document's presentation) keeps its own cover until `drawn`, and offers Play when the lecture is `waiting`.
+ */
+export const EMBED_MESSAGE = 'presmium:state'
+
+export type EmbeddedLecture = 'loading' | 'waiting' | 'playing' | 'paused' | 'failed'
+
+export interface EmbedState {
+  type: typeof EMBED_MESSAGE
+  drawn: boolean
+  section?: string
+  step?: number
+  /** Absent when the page plays no lecture. `waiting`: the browser refused autoplay; the reader's Play starts it. */
+  lecture?: EmbeddedLecture
+}
+
+let last: EmbedState = { type: EMBED_MESSAGE, drawn: false }
+
+/** Sends the page's state, merged with what was sent before, to the embedding page; nothing when not in a frame. */
+export function notifyEmbedder(change: Partial<Omit<EmbedState, 'type'>>): void {
+  if (typeof window === 'undefined' || window.parent === window) return
+  last = { ...last, ...change }
+  window.parent.postMessage(last, '*')
+}

package/src/escape-html.ts

@@ -0,0 +1,4 @@
+/** Text as it reads in HTML, in an element or an attribute's value; apart from `html.ts`, so that escaping loads no HTML parser. */
+export function escapeHtml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}

package/src/html.ts

@@ -1,9 +1,6 @@
 import { parseFragment } from 'parse5'
 import type { DefaultTreeAdapterMap } from 'parse5'
-
-export function escapeHtml(text: string): string {
-  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
-}
+import { escapeHtml } from './escape-html.ts'
 
 export interface HtmlAttribute {
   name: string

package/src/index.ts

@@ -25,7 +25,8 @@ export { errorMessage, isRecord, PreviewPreparing } from './errors.ts'
 export { createEventBus } from './events.ts'
 export { CREDENTIAL_VARIABLE, environmentExecutor, failedRun, languageId } from './execution.ts'
 export { gitConfigArgs, gitEnvironment } from './git.ts'
-export { escapeHtml, htmlAttributes, mapHtmlUrls, URL_ATTRIBUTES } from './html.ts'
+export { escapeHtml } from './escape-html.ts'
+export { htmlAttributes, mapHtmlUrls, URL_ATTRIBUTES } from './html.ts'
 export type { HtmlAttribute } from './html.ts'
 export { hostName, localRequestRefusal } from './requests.ts'
 export type { RequestHeaders } from './requests.ts'
@@ -39,9 +40,13 @@ export type { KernelOptions } from './kernel.ts'
 export { deckLocale, localeOf } from './locale.ts'
 export { ANCHOR_LOCK_PATH, AnchorLock } from './lock.ts'
 export { prefixedLogger } from './logging.ts'
-export { lowerMyst, roleMark } from './lower-myst.ts'
+export { lowerMyst } from './lower-myst.ts'
 export type { LinkedType, LoweredMarkdown, LowerOptions } from './lower-myst.ts'
-export { connectPreviewFrame, isPreviewActive, isPreviewEmbedded, previewAppearance, previewFrameAncestors, reportPreview, reportStaleModule } from './preview-frame.ts'
+export { isPreviewActive, isPreviewEmbedded, previewAppearance, reportPreview, siteFrameAncestors } from './preview-frame.ts'
+export { connectPreviewFrame } from './preview-frame-connect.ts'
+export { reportStaleModule, STALE_MODULE_EVENT, STALE_MODULE_PATTERN } from './stale-module.ts'
+export { EMBED_MESSAGE, notifyEmbedder } from './embed.ts'
+export type { EmbeddedLecture, EmbedState } from './embed.ts'
 export { keyBelongsToTarget, watchFocusSource } from './keyboard.ts'
 export type { PreviewFrame, PreviewPage, PreviewProblem, PreviewTextEdit, PreviewTextHandle } from './preview-frame.ts'
 export { previewEditBinding } from './preview-edit.ts'
@@ -65,7 +70,7 @@ export type { StepKeys } from './step-keys.ts'
 export { parseDuration } from './durations.ts'
 export { stepStateAt } from './steps.ts'
 export { ABSOLUTE_URL, NON_FILE_URL, urlSlug } from './urls.ts'
-export { isButton } from './lower-myst.ts'
+export { isButton, roleMark } from './myst-marks.ts'
 export { componentProps, findComponentRenderer, hasRendererExtension, WEB_RENDERER_PACKAGE, withPublishedAssets } from './renderer-components.ts'
 export { htmlAsText, isProseRun } from './run-outputs.ts'
 export { safeDecodeURIComponent } from './uri-decoding.ts'

package/src/ir.ts

@@ -326,11 +326,23 @@ export interface SiteDocument {
   description?: string
   lang?: string
   tags?: string[]
+  /** Whether it has a presentation, before its IR is compiled (`DocumentSummary.slides`). */
+  slides?: boolean
   doc?: IRDocument
   translations?: { lang: string, doc: IRDocument }[]
   nodeVitePlugins?: NodeVitePlugin[]
 }
 
+/**
+ * A built site keeps its viewer apps below its path, each at `<APP_DIR>/<key>/` by its content. A presentation built as
+ * part of a site (renderer option `appBase`, the site's path) names its app there, so the site's pages and all its
+ * presentations load one app.
+ */
+export const APP_DIR = '_app'
+
+/** A site serves a document's presentation (`renderers.slides`) below the document's pages, at `<document>/<SLIDES_DIR>/`. */
+export const SLIDES_DIR = 'slides'
+
 export interface SiteSpec {
   title: string
   documents: SiteDocument[]

package/src/lower-myst.ts

@@ -1,4 +1,6 @@
-import { escapeHtml as escape, mapHtmlUrls } from './html.ts'
+import { escapeHtml as escape } from './escape-html.ts'
+import { mapHtmlUrls } from './html.ts'
+import { isButton, roleMark } from './myst-marks.ts'
 import type { MdastNode } from './ir.ts'
 
 export type LinkedType = 'image' | 'link' | 'definition'
@@ -198,11 +200,6 @@ function cardsAs(options: LowerOptions): 'element' | 'headings' {
   return options.cards ?? (options.iframes === 'element' ? 'element' : 'headings')
 }
 
-/** Whether a MyST node has the class `button`, which renders a link or span as a button. */
-export function isButton(node: MdastNode): boolean {
-  return typeof node.class === 'string' && node.class.split(/\s+/).includes('button')
-}
-
 function layout(node: MdastNode, ctx: Lowering): MdastNode[] {
   const all = (nodes: MdastNode[] = []) => nodes.flatMap(child => lower(child, ctx))
   const element = cardsAs(ctx.options) === 'element'
@@ -248,12 +245,6 @@ function layout(node: MdastNode, ctx: Lowering): MdastNode[] {
   return all(items)
 }
 
-export function roleMark(node: MdastNode): string {
-  const options = typeof node.options === 'object' && node.options !== null ? node.options as Record<string, unknown> : {}
-  const value = typeof options.value === 'string' ? options.value.trim() : ''
-  return `〔${String(node.name ?? '')}${value ? ` ${value}` : ''}〕`
-}
-
 function footnoteNumber(node: MdastNode): string {
   return String(node.enumerator ?? node.label ?? node.identifier)
 }

package/src/myst-marks.ts

@@ -0,0 +1,15 @@
+import type { MdastNode } from './ir.ts'
+
+// What a viewer reads from MyST nodes as they are, apart from their lowering (`lower-myst.ts`), which rewrites HTML.
+
+/** Whether a MyST node has the class `button`, which renders a link or span as a button. */
+export function isButton(node: MdastNode): boolean {
+  return typeof node.class === 'string' && node.class.split(/\s+/).includes('button')
+}
+
+/** The mark a role without content shows: its name and value. */
+export function roleMark(node: MdastNode): string {
+  const options = typeof node.options === 'object' && node.options !== null ? node.options as Record<string, unknown> : {}
+  const value = typeof options.value === 'string' ? options.value.trim() : ''
+  return `〔${String(node.name ?? '')}${value ? ` ${value}` : ''}〕`
+}