The Scrawl-canvas developer Runbook

(Valid for Scrawl-canvas v8.17.0)

Purpose of the Runbook

This Runbook tries to explain the design, architecture, code and toolchains associated with the Scrawl-canvas repository.

The Runbook is not, in a strict sense, a technical document because it doesn't set out in fine-grain detail how contributing developers (repo-devs) should structure their contributions to the library, or how developers using the library for their own products/projects (product-devs) should approach their work.

Rather, the Runbook is more of a brain-dump which gives information on the design patterns and architectural choices repo-devs made while developing SC, alongside pointers to where in the repo particular functionality lives and how it works. It also offers advice to product-devs on some best practices when using SC which may, hopefully, save them a bit of time.

Contents

Repository structure, and release protocol

• GitHub branch policy
• v8 branch
• v8-dev branch
• History
• Repository structure
• Top level documentation
• Development toolchain
• Git, GitHub, NPM
• Yarn
• Building: Rollup
• Building: Docco
• Building: Showdown
• Testing: ESlint
• Testing: Knip
• Testing: TypeScript
• Development and testing: Browser-sync
• Development and testing: source code
• Releasing a new version of Scrawl-canvas

Scrawl-canvas source code structure

• Folder overview
• Core coding guidelines
• Common file structures
• Factory files
• Mixin files
• Other files

Scrawl-canvas page load initialization

• The scrawl.js file
• The core/init.js file
• Imports
• Discovery activity
• The Scrawl-canvas animation loop
• Core constants, flags and event listeners
• Shared constants
• Shared functions
• System listeners and user interactions
• Scrawl-canvas pools
• Scrawl-canvas filter engine
• Scrawl-canvas color engine
• Scrawl-canvas workstore

Scrawl-canvas objects overview

• Object creation and the SC library
• The base mixin
• Object naming
• The Scrawl-canvas library
• Locating objects in the SC library
• Deleting objects, and SC library hygiene
• Getting and setting object attributes
• Object serialization and cloning
• Clone functionality
• Exceptions to the outlined processes
• Canvas and Stack factory functions
• Cell factory function
• Animation and RenderAnimation factory functions
• Loom and Mesh entity factory functions
• Image-based asset management factory functions
• Pool-based factory functions

Scrawl-canvas artefacts and the DOM

• Scrawl-canvas stacks
• A brief history of SC Stacks
• HTML elements that can become Stack or Element artefacts
• CSS considerations
• CSS classes
• SC artefact object functionality
• Accessibility
• Progressive enhancement
• Advanced canvas-related functionality
• How to test progressive enhancement locally
• Responsiveness
• Tracking Artefact element shape and size
• Perspective and 3D rotation
• Euler rotation
• Artefact offset
• User interaction and the here object
• Subscribing to here updates using trackHere
• Setting and managing events
• SC zone events (drag zones, keyboard zones)
• Canvas artefact notes
• Wrapping the canvas DOM element
• Accessibility
• Responsiveness
• Color
• Ghosting effect
• Canvas performance
• Canvas DOM elements and the wider page environment
• Page scaling
• Screen device-pixel-ratio
• Wide-gamut color support - display-p3
• Emulating CSS object-fit
• Canvas base Cell pass-through functions
• Stack artefact notes
• Wrapping the Stack artefact's DOM element
• Stack and Element corners
• Element artefact notes
• Wrapping the Element artefact's DOM element

The Scrawl-canvas scene graph

• SC scene graph hierarchy
• SC Group objects
• Create, serialize, clone and kill Group objects
• Group discovery in the SC library, and beyond
• Add Group objects to Stack/Cell objects, and remove them
• Group visibility, ordering and sorting
• Add artefact/entity objects to Group objects, and remove them
• Artefact sorting
• Batch update artefact/entity object attributes using Group object functions
• Delta manipulations
• Artefact class manipulations
• Stack artefact and Cell object equivalent functionality
• Apply visual filters to Groups containing entity objects
• Cell entity, and Stack artefact, end-user interactions
• SC Cell objects
• Types of Cell objects
• Base Cells
• Pool Cells
• Layer Cells
• Create, serialize, clone and kill Cell objects
• Cell discovery in the SC library, and beyond
• The Cell engine
• Cell dimensions
• Cell backgrounds
• Cell display manipulation - the splitShift() function
• Cell data manipulation - the getCellData() and paintCellData() functions
• Display cycle considerations
• Cell clear functionality
• Cell compile functionality
• Layer Cell show functionality
• Base Cell show functionality
• Cell opacity, composition and filters
• Cell, and entity, state
• Create, serialize, clone and kill State objects
• State object attributes
• Updating State object attributes
• Fill and stroke details
• Line styling details
• Shadow styling details
• Text styling details
• CSS/SVG filter details
• Using Cells as Pattern styles
• Object processing order within the scene graph

Animation and the Display cycle

• Animation objects
• Animation object serialization and cloning
• Accessibility considerations around animation
• Generic animations
• The fn function
• The hook functions
• Animation choke functionality
• System-instantiated animations
• Time-based animations
• Ticker objects
• Create, serialize, clone and kill Ticker objects
• Ticker attributes
• Ticker duration
• Ticker cycles
• Ticker subscribers
• Running and halting tickers
• Ticker progress
• Temporal direction
• Subscriber communication
• Tween objects
• Create and serialize Tween objects
• Clone Tween objects
• Kill Tween objects
• Tween attributes
• Tweens and Tickers
• Tween start and duration times
• Tween targets
• Tween Definition objects
• Easing engine functions
• Action objects
• Create, serialize, clone and kill Action objects
• Action attributes
• Action and revert functions
• Display animations and the Display cycle
• The scrawl.makeRender() factory function
• Create, serialize, clone and kill RenderAnimation objects
• RenderAnimation attributes
• RenderAnimation targets
• RenderAnimation observers
• RenderAnimation hook functions
• Delta animation
• Define a delta animation
• Control a delta animation

Scrawl-canvas events and signals

• System events
• Actioning systemic user interactions
• Dynamic asset management
• Responsive images
• Responsive video and video streams
• Third-party canvas sources
• Pointer (mouse and touch) interaction
• SC event listener convenience functions
• The addListener() function
• The addNativeListener() function
• Cascading events
• Group hover event functionality
• Drag-and-drop functionality
• Non-pointer interaction
• Scrawl-canvas Anchor and Button objects
• Keyboard navigation
• User interaction with form controls
• Keyboard shortcut management
• The Scrawl-canvas signalling system
• Marking objects as dirty
• Cleaning dirty objects

Accessibility

• Impact of WCAG requirements on <canvas> elements
• Text alternatives for non-text content
• SC and <canvas> element children
• Canvas label, description and title
• Canvas roles
• Captions and other alternatives for multimedia
• SC and accessible multimedia
• Managing audio assets
• Managing video asset captions and subtitles
• Content can be presented in different ways
• SC support for the content presentation requirements
• Content is easier to see and hear
• SC Color space support
• SC function hooks to adapt to color-based user preferences settings
• SC support for browser zoom (not pinch zoom)
• Functionality is available from a keyboard
• Keyboard event management for SC Canvas artefacts
• Users have enough time to read and use the content
• Managing SC Animations
• Content does not cause seizures and physical reactions
• SC function hooks to adapt to motion-based user preferences settings
• Users can easily navigate, find content, and determine where they are
• Button and link functionality in SC Canvas artefact displays
• Focus management for interactive SC entitys
• Apply canvas decoration to HTML headers using SC Snippet functionality
• Users can use different input modalities beyond keyboard
• Text is readable and understandable
• SC text management functionality
• Content appears and operates in predictable ways
• Users are helped to avoid and correct mistakes
• Content is compatible with current and future user tools

Scrawl-canvas asset management and use

• [TODO: write doc]

Scrawl-canvas styles management and use

• [TODO: write doc]

The Scrawl-canvas positioning system

• Background
• The rotation-reflection point
• Absolute and relative positioning
• The start artefact attribute
• The offset and position artefact attributes
• The handle artefact attribute
• Positioning by reference
• The lockTo artefact attribute
• Pivot specifics
• Mimic specifics
• Path specifics

Scrawl-canvas filters

• CSS and SVG filters
• The SC filter factory
• The scrawl.makeFilter() factory function
• Create Filter objects
• Serialize, clone and kill Filter objects
• Filter application
• Stacking filters
• Chaining filters
• Input and output identifiers
• Filter opacity
• Using objects as filter stencils
• Memoizing a filtered object's output
• Internal memoization functionality
• One-time capture of a filtered object's output
• Internal coding protocols
• Apply filters to Cell objects
• Apply filters to Group objects
• Apply filters to entity objects
• Apply filters to EnhancedLabel entity objects
• The SC filter engine
• Code efficiency
• Filter regions
• External caching using the SC workstore
• Filter engine internal cache
• Additional resources used by the filter engine
• The seeded random numbers generator
• Noise generators
• Protocol for processing a filter request
• SC filter primitive functions
• Alpha channel filters
• Action: area-alpha
• Action: channels-to-alpha
• Action: chroma
• Action: colors-to-alpha
• Color channels filters
• Action: alpha-to-channels
• Action: average-channels
• Action: clamp-channels
• Action: flood
• Action: grayscale
• Action: invert-channels
• Action: lock-channels-to-levels
• Action: map-to-gradient
• Action: modulate-channels
• Action: set-channel-to-level
• Action: step-channels
• Action: threshold
• Action: tint-channels
• Action: vary-channels-by-weights
• Composition filters
• Action: blend
• Action: compose
• Action: process-image
• Convolution filters
• Action: blur
• Action: corrode
• Action: emboss
• Action: gaussian-blur
• Action: matrix
• Action: newsprint
• Action: pixelate
• Action: tiles
• Action: zoom-blur
• Displacement filters
• Action: displace
• Action: glitch
• Action: offset
• Action: random-noise
• Action: swirl
• OK color space filters
• Action: alpha-to-luminance - color channels filter
• Action: deconvolute - convolution filter
• Action: luminance-to-alpha - alpha channels filter
• Action: modify-ok-channels - color channels filter
• Action: modulate-ok-channels - color channels filter
• Action: negative - color channels filter
• Action: reduce-palette - color channels filter
• Action: rotate-hue - color channels filter
• Action: unsharp - convolution filter
• SC predefined filter effects
• Method: alphaToChannels
• Method: alphaToLuminance
• Method: areaAlpha
• Method: blend
• Method: blue
• Method: blur
• Method: brightness
• Method: channelLevels
• Method: channels
• Method: channelstep
• Method: channelsToAlpha
• Method: chroma
• Method: chromakey
• Method: clampChannels
• Method: compose
• Method: corrode
• Method: curveWeights
• Method: cyan
• Method: deconvolute
• Method: displace
• Method: edgeDetect
• Method: emboss
• Method: flood
• Method: gaussianBlur
• Method: glitch
• Method: gray
• Method: grayscale
• Method: green
• Method: image
• Method: invert
• Method: luminanceToAlpha
• Method: magenta
• Method: mapToGradient
• Method: matrix
• Method: matrix5
• Method: modifyOk
• Method: modulateOk
• Method: negative
• Method: newsprint
• Method: notblue
• Method: notgreen
• Method: notred
• Method: offset
• Method: offsetChannels
• Method: pixelate
• Method: randomNoise
• Method: red
• Method: reducePalette
• Method: rotateHue
• Method: saturation
• Method: sepia
• Method: sharpen
• Method: swirl
• Method: threshold
• Method: tiles
• Method: tint
• Method: unsharp
• Method: yellow
• Method: zoomBlur

The Scrawl-canvas particle engine

• [TODO: write doc]

The Scrawl-canvas text-layout engine

• [TODO: write doc]

Scrawl-canvas graphical entity functionality

• Create and display graphical entitys
• Positioning entitys on the canvas display
• Styling entitys
• Interactive entitys
• Link zones
• Action zones
• Entity drag-and-drop
• Accessible entitys
• Keyboard accessibility
• Form controls

Simple entitys

• [TODO: write doc]

Path-based entitys

• [TODO: write doc]

Image-based entitys

• [TODO: write doc]

Text-based entitys

• [TODO: write doc]

Particle-based entitys

• [TODO: write doc]

Scrawl-canvas snippets

• [TODO: write doc]

Scrawl-canvas packets and serialization

• [TODO: write doc]

Coding, and managing, the Scrawl-canvas website

• [TODO: write doc]